Guides

Managing Bills

Retrieve bills for a subscription and manage bill statuses via the API.

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.

/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",
      "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:

📘

Note

void is a terminal status. Once a bill has been marked as voided, it cannot be transitioned to any other status.