BillKit/DocsConsole
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·OpenAPI v1.1.0

Parameters

ParameterDescription
subscription_idstring · pathrequiredId of the subscription, which starts sub_.
expandstring | null · queryoptionalComma-separated related objects to include in the response. Expandable here: customer, price, refund_eligibility. An unknown name is a 400, and embedding another resource needs that resource's read scope. At 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.

To decide whether to serve the customer, read serves_customer. A paused or cancelling subscription keeps status: active until a background job closes it shortly after its period ends, so status alone over-grants. Read renewal_state when you need to know what happens at the period boundary.

next_charge_amount_cents is what the next renewal will charge, with a recurring coupon and any exclusive VAT applied. The list, every mutation response and every subscription.* webhook carry the same value. It is null when the subscription will not renew or its price is metered.

Test it

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

Errors

StatusCause
400The request was refused (type: invalid_request_error): a required parameter is missing (parameter_missing), one failed validation (parameter_invalid) or is not one the operation takes (parameter_unknown), and param names it.
401No credential, or one that does not authenticate.
402The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused).
403Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the subscriptions:read scope.
404No such object in this account and mode.
429Rate limited. Retry-After says when to try again.
500Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key.
503Temporarily unable to serve. reason says whether the request was attempted.
Request · curl
curl -X GET https://api.billkit.eu/v1/subscriptions/sub_9XKp2vQ1 \
  -H "Authorization: Bearer $BILLKIT_API_KEY"
Response · 200 OK
{
  "cancel_at_period_end": false,
  "canceled_at": 1789392000,
  "cancellation_reason": "refund_issued",
  "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",
  "discount": {
    "coupon_id": "coup_9XKp2vQ1",
    "ends_at": 1789392000,
    "object": "discount"
  },
  "dunning_attempts_notified": 0,
  "dunning_last_notified_at": 1789392000,
  "id": "sub_9XKp2vQ1",
  "last_payment_at": 1789392000,
  "last_payment_id": "pay_9XKp2vQ1",
  "livemode": false,
  "mrr_cents": 1900,
  "next_charge_amount_cents": 1900,
  "next_payment_attempt": 0,
  "object": "subscription",
  "payment_count": 0,
  "payment_method": {
    "brand": "string",
    "exp_month": 0,
    "exp_year": 0,
    "last4": "string",
    "type": "creditcard"
  },
  "price": {
    "active": false,
    "amount_cents": 1900,
    "billing_scheme": "per_unit",
    "currency": "EUR",
    "id": "obj_9XKp2vQ1",
    "interval": "month",
    "object": "price.summary",
    "payment_methods": [
      "creditcard"
    ],
    "payment_methods_from_account": false,
    "product_id": "prod_9XKp2vQ1",
    "product_name": "Ada Lovelace",
    "tax_behavior": "inclusive",
    "tiers_mode": "graduated",
    "trial_days": 0,
    "unit_amount_decimal": "string",
    "usage_type": "licensed"
  },
  "price_id": "price_9XKp2vQ1",
  "refund_eligibility": {
    "amount_cents": 1900,
    "currency": "EUR",
    "days_remaining": 0,
    "eligible": false,
    "object": "refund_eligibility",
    "reason": "no_charge",
    "window_ends_at": 1789392000
  },
  "renewal_state": "auto_renew",
  "serves_customer": false,
  "status": "incomplete",
  "trial_end": 0,
  "trial_start": 0
}