BillKit/Docs Console
Subscriptions

List subscriptions

Returns subscriptions for the account, newest first. Cursor-paginated, and filterable by customer and status.

GET/v1/subscriptions
Operation list_subscriptions · Scope subscriptions:read · Spec snapshot 2026-09-13

Parameters

ParameterDescription
customer_idstring | null · queryoptionalAt most 64 characters.
statusstring | null · queryoptionalAt most 128 characters.
renewal_statestring | null · queryoptionalAt most 128 characters.
limitinteger · queryoptionalDefaults to 10. Between 1 and 100.
starting_afterstring | null · queryoptionalAt most 128 characters.
expandstring | null · queryoptionalAt most 256 characters.

Cursor-paginated. limit caps a page and starting_after takes the last id you saw.

Returns

A list object: data holds the page and has_more says whether another one exists. Page forward by passing the last id of the page as starting_after; a short page is not the end of the list.

Paging is forward-only. To go back, keep the cursors you have already used.

Test it

Filter to status=past_due against a sandbox with an advanced test clock to see the dunning cohort your retry job would pick up.

Errors

Status Cause
401 Missing or invalid API key.
403 Key is missing the subscriptions:read scope.
422 Validation Error
429 Rate limited. Back off and retry.
Request · curl 
curl -X GET https://api.billkit.eu/v1/subscriptions \
  -H "Authorization: Bearer $BILLKIT_SECRET_KEY"
Response · 200 OK 
{
  "data": [
    {
      "cancel_at_period_end": false,
      "canceled_at": 1789392000,
      "cancellation_reason": "string",
      "created": 1789392000,
      "current_period_end": 0,
      "current_period_start": 0,
      "customer": {
        "country_code": "NL",
        "email": "ada@example.com",
        "id": "obj_9XKp2vQ1",
        "name": "Ada Lovelace",
        "object": "customer.summary"
      },
      "customer_id": "cus_9XKp2vQ1",
      "dunning_attempts_notified": 0,
      "dunning_last_notified_at": 1789392000,
      "dunning_max_attempts": 0,
      "id": "sub_9XKp2vQ1",
      "last_payment_at": 1789392000,
      "last_payment_id": "pay_9XKp2vQ1",
      "livemode": false,
      "mrr_cents": 1900,
      "object": "subscription",
      "payment_count": 0,
      "price": {
        "active": false,
        "amount_cents": 1900,
        "currency": "EUR",
        "id": "obj_9XKp2vQ1",
        "interval": "string",
        "object": "price.summary",
        "payment_methods": [],
        "product_id": "prod_9XKp2vQ1",
        "product_name": "Ada Lovelace",
        "trial_days": 0,
        "unit_amount_decimal": "string",
        "usage_type": "string"
      },
      "price_id": "price_9XKp2vQ1",
      "refund_eligibility": {
        "amount_cents": 1900,
        "currency": "EUR",
        "days_remaining": 0,
        "eligible": false,
        "object": "refund_eligibility",
        "reason": "string"
      },
      "renewal_state": "string",
      "serves_customer": false,
      "status": "string",
      "trial_end": 0,
      "trial_start": 0
    }
  ],
  "has_more": false,
  "object": "list"
}