Managing Bills

Retrieving bills

You can retrieve bills for a specific subscription by submitting a GET request to the /subscriptions/{subscription_id}/bills endpoint. This returns a paginated list of bills and supports filtering by status.

For more information, please refer to our bills API reference.

To retrieve a single bill, submit a GET request to the /subscriptions/{subscription_id}/bills/{bill_id} endpoint — see the fetch bill API reference.

You can also list bills across all of your subscriptions via the top-level GET /bills endpoint, which supports filtering by subscription_id, customer_id and status — see the fetch all bills API reference.

Every bill carries a cycle_number — the 1-based number of the billing cycle it charges for. The subscription's first charged bill is cycle 1 (a free trial does not count as a cycle), and the number is set when the bill is created and never changes, so you can group payment activity by billing cycle even when statuses or due dates change later.

/subscriptions/{subscription_id}/bills response:

{
  "data": [
    {
      "id": "01HNY4G8G8P4E1T4YJ9N8B1Z9M",
      "subscription_id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
      "customer": {
        "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240"
      },
      "status": "paid",
      "amount": {
        "base": 19.99,
        "discount": 0,
        "total": 19.99,
        "status": "finalised"
      },
      "currency": "GBP",
      "due_date": "2025-12-01T09:00:00Z",
      "cycle_number": 2,
      "transactions": [
        {
          "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "status": "success",
          "type": "payment",
          "payment_method": "card"
        }
      ],
      "created_at": "2025-11-01T09:00:00Z",
      "links": [
        {
          "rel": "self",
          "href": "/v1/subscriptions/01HNY4G8G5ZMAXQB8T0Z1Y1ZMW/bills/01HNY4G8G8P4E1T4YJ9N8B1Z9M"
        }
      ]
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 20,
    "total": 1,
    "links": [
      {
        "rel": "self",
        "href": "/v1/subscriptions/01HNY4G8G5ZMAXQB8T0Z1Y1ZMW/bills?offset=0&limit=20"
      }
    ]
  }
}

Updating bill status

You can manually update a bill's status using the following endpoints:

• Mark as paid — POST /subscriptions/{subscription_id}/bills/{bill_id}/paid — marks a draft, open or past_due bill as paid.
• Void a bill — POST /subscriptions/{subscription_id}/bills/{bill_id}/void — voids a draft, open, past_due or paid bill, preventing any further payment attempts.

Changing a bill due date

You can move a draft bill's due date — forward or backward — with PATCH /subscriptions/{subscription_id}/bills/{bill_id}/due_date. All future bills re-anchor automatically: each next bill is calculated from the previous bill's due date plus the subscription's billing cycle, so only the draft bill needs moving and the cycle length itself never changes. For example, on a monthly subscription, moving the upcoming bill from June 1st to June 15th means the following bills fall due on July 15th, August 15th, and so on.

The following rules apply:

• Only bills in draft status can be changed.
• The new due date must be tomorrow (UTC) or later. There is no upper bound on forward moves.
• While the subscription has an active payment recovery, the due date cannot be moved earlier; forward moves are unaffected.