---
title: "Lists all bills"
method: GET
path: "/bills"
tags: ["Bills"]
---

# Lists all bills

`GET /bills`

Returns AP bills with pagination plus filters for vendor, subsidiary, approval state, and balances due.
Use bill ids with retrieve-a-bill before performing full updates or attaching documents.

## Query parameters

- `limit` integer
- `cursor` string — If defined, a cursor to retrieve the next page.
- `subsidiary_id` string, uuid
- `updated.gt` string, date-time
- `vendor_id` string, uuid
- `status` 'UNPAID' | 'PAID' | 'PARTIALLY_PAID' | 'CREDITED' | 'PARTIALLY_CREDITED' | 'APPLIED'

## Response `200`

OK

- object
  - `bills` Bill[], required
    - `vendor_id` string, uuid, required
    - `expense_number` string, required
    - `items` object[], required
      - `description` string
      - `account_code` string, required — The account code found in the Chart of Accounts
      - `amount` RoundedMonetaryAmount, required — A monetary amount that must be rounded to the currency's default decimal places (e.g., 2 decimal places for USD).
        - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. Must be rounded to the currency's default decimal places (e.g. '1.01' in USD represents 1 dollar and 1 cent).
        - `currency` string, required — Currency code following ISO-4217
      - `tax_rate` ExpenseTaxRate
        - `percentage` number, required
        - `tax_amount` RoundedMonetaryAmount, required — A monetary amount that must be rounded to the currency's default decimal places (e.g., 2 decimal places for USD).
          - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. Must be rounded to the currency's default decimal places (e.g. '1.01' in USD represents 1 dollar and 1 cent).
          - `currency` string, required — Currency code following ISO-4217
        - `country` string, required — Two-letter country code (ISO 3166-1 alpha-2).
        - `type` 'VAT' | 'SALES_TAX', required
        - `description` string, required
        - `tax_code` string — Code of a predefined tax rate. When provided, the rate's percentage, country, and description are used instead of the inline values.
        - `coverage` 'INCLUSIVE' | 'EXCLUSIVE', required
      - `service_period` CalendarPeriod
        - `start` string, date, required
        - `end` string, date, required
      - `fields` object[]
        - `field_id` string, uuid, required
        - `field_value_id` string, uuid, required
      - `id` string, uuid, required
    - `bill_date` string, date, required
    - `due_date` string, date, required
    - `impact_date` string, date
    - `subsidiary_id` string, uuid
    - `external_references` ExternalReference[]
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `exchange_rate` ExchangeRate
      - `base` string, required — Currency code following ISO-4217
      - `target` string, required — Currency code following ISO-4217
      - `rate` string, required
      - `date` string, date, required
    - `id` string, uuid, required
    - `status` 'UNPAID' | 'PAID' | 'PARTIALLY_PAID' | 'CREDITED' | 'PARTIALLY_CREDITED' | 'APPLIED', required
    - `updated_at` string, date-time, required — Timestamp when the bill was last modified
  - `pagination` Pagination, required
    - `next_cursor` string — If defined, a cursor to retrieve the next page.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/rillet/apis/rillet-accounting-api.md) · [All operations](https://skmtc.net/rillet/apis/rillet-accounting-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rillet/rillet-accounting-api/versions/a2ab794dd5f2/schema)