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

# List all bills

`GET /bills`

Returns a paginated list of bills across all subscriptions.

## Query parameters

- `subscription_id` string
- `customer_id` string, uuid
- `status` 'draft' | 'open' | 'paid' | 'void' | 'past_due' | 'unpaid'
- `offset` integer
- `limit` integer

## Response `200`

List of bills.

- BillListPaged
  - `meta` object
    - `count` integer — The number of records returned as part of the response.
    - `offset` integer — The starting record number.
    - `limit` integer — The maximum number of records that can be returned as part of the response.
    - `total` integer — The total number of records contained in the query response.
    - `links` object[]
      - `rel` 'self' | 'first' | 'last' | 'prev' | 'next'
      - `href` string — Link to the resource which should be appended to base URL.
      - `title` string — Description of the link.
  - `data` Bill[]
    - `id` string, required — Unique ID assigned by Acquired to the bill when it is created.
    - `subscription_id` string, required — ID of the subscription this bill belongs to.
    - `customer` object, required — The customer associated with this bill.
      - `customer_id` string, uuid, required — Unique ID assigned by Acquired to the customer.
    - `status` 'draft' | 'open' | 'paid' | 'void' | 'past_due' | 'unpaid', required — Current lifecycle status of the bill.
    - `amount` object, required — Breakdown of the bill amount in major currency units. Reflects any active subscription discount.
      - `base` number, required — The pre-discount amount for this billing cycle.
      - `discount` number, required — The discount amount applied to this bill.
      - `total` number, required — The final amount due after discount (`base` minus `discount`).
      - `status` 'finalised' | 'projected', required — Whether the amount was finalised at bill close (`finalised`) or is still a forward-looking projection (`projected`).
    - `currency` string, required — The currency the bill is denominated in.
    - `due_date` string, date-time, required — When this bill is due to be paid.
    - `transactions` object[], required — List of transactions associated with this bill.
      - `transaction_id` string, uuid, required — Unique ID of the payment attempt against this bill.
      - `status` string, required — Outcome status of the payment attempt.
      - `type` string, required — The kind of transaction recorded against the bill, e.g. `payment`.
      - `payment_method` string, required — The payment method used for the attempt, e.g. `card`.
    - `created_at` string, date-time, required — When the bill record was created.
    - `links` object[], required
      - `rel` 'self'
      - `href` string — Link to the resource which should be appended to base URL.
      - `method` string — The HTTP method to use with the link.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.dev/acquired/apis/acquired-api.md) · [All operations](https://skmtc.dev/acquired/apis/acquired-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/acquired/acquired-api/revisions/7ae178a046f2/schema)