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.

/subscriptions/{subscription_id}/bills response:

{
  "data": [
    {
      "id": "01HNY4G8G8P4E1T4YJ9N8B1Z9M",
      "subscription_id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
      "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240",
      "status": "paid",
      "amount": 1999,
      "currency": "GBP",
      "due_date": "2025-12-01T09:00:00Z",
      "transactions": [
        {
          "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 or open bill as paid.
Void a bill — POST /subscriptions/{subscription_id}/bills/{bill_id}/void — voids a draft or open bill, preventing any further payment attempts.

📘
Note
Both paid and void are terminal statuses. Once a bill has been marked as paid or voided, it cannot be transitioned to any other status.