BillKit/Docs Console
Subscriptions

Retrieve a subscription

Fetches one subscription by id, including its current period, price and renewal state.

GET/v1/subscriptions/{subscription_id}
Operation get_subscription · Scope subscriptions:read · Spec snapshot 2026-09-13

Parameters

ParameterDescription
subscription_idstring · pathrequiredNo description in the spec.
expandstring | null · queryoptionalAt most 256 characters.

Returns

The subscription object. A subscription belonging to the other mode, or to another account, is a 404 rather than a 403, so no id existence leaks across tenants.

Read renewal_state, not just status, when you need to know what happens at the period boundary: a subscription can be active today and set to cancel or paused at renewal.

Test it

Read the same subscription in the console under Subscriptions. The two views are the same row.

Errors

Status Cause
401 Missing or invalid API key.
403 Key is missing the subscriptions:read scope.
404 No such object, or it belongs to the other mode.
422 Validation Error
429 Rate limited. Back off and retry.
Request · curl 
curl -X GET https://api.billkit.eu/v1/subscriptions/sub_9XKp2vQ1 \
  -H "Authorization: Bearer $BILLKIT_SECRET_KEY"
Response · 200 OK 
{
  "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": [
      "string"
    ],
    "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
}