Subscriptions

Generated page, from the OpenAPI specification the gateway serves (GET /v1/openapi.json). Do not edit it by hand: it is rewritten on every build.

Method	Path	Description
GET	/v1/subscriptions	List subscriptions
POST	/v1/subscriptions	Create a subscription
GET	/v1/subscriptions/{id}	Retrieve a subscription
DELETE	/v1/subscriptions/{id}	Cancel a subscription

GET /v1/subscriptions

List subscriptions

ⓘ A flat list, capped at fifty, with no pagination — an account beyond fifty standing instructions is running a billing product, and that is read in the dashboard. Stating the cap is better than a page parameter that would mean nothing.

Parameters

Name	In	Required	Description
status	query	no	Filter on status (active, past_due, cancelled…).

Responses

• 200 — OK (object)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

POST /v1/subscriptions

Create a subscription

Opens a standing instruction to bill a customer at a plan's cadence.

⚠️ A SUBSCRIPTION NEVER DEBITS BY ITSELF. It issues an invoice when due and collects on a stored payment method; there is no direct-debit mandate on this platform, and no rail here carries one. That is why creation requires the can_initiate_payment scope: the power a subscription confers is exactly the power to collect, granted once for an open-ended series.

The plan is created in the dashboard; plan_id is its public identifier.

Parameters

Name	In	Required	Description
Idempotency-Key	header	no	An idempotency key specific to THIS operation.

Request body

Field	Type	Required	Description
plan_id	string	yes	The plan to bill, by its public id.
customer_id	string	no	The customer being billed, if they are registered with us.
payment_method_ref	string	no	The payment method to debit on each due date.

Responses

• 201 — Subscription created (object)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 422 — Plan not found, inactive, or belonging to another account (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

GET /v1/subscriptions/{id}

Retrieve a subscription

The subscription and its counters. A non-zero retry_count signals a collection currently failing on the present cycle.

Parameters

Name	In	Required	Description
id	path	yes

Responses

• 200 — OK (object)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 404 — No subscription with that identifier (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

DELETE /v1/subscriptions/{id}

Cancel a subscription

Immediate cancellation by default. ?at_period_end=true lets the paid period run to its end and cancels instead of renewing at the next due date.

ⓘ Neither one refunds what has already been collected: a refund is a separate operation, deliberately.

Parameters

Name	In	Required	Description
id	path	yes
at_period_end	query	no	true = cancel at the end of the paid period rather than immediately.

Responses

• 200 — Cancelled (object)
• 401 — API key missing or rejected (Error)
• 403 — The key does not carry the required scope, or the account is not active (Error)
• 404 — No subscription with that identifier (Error)
• 422 — The subscription cannot be cancelled in its current state (Error)
• 429 — The key's request budget is exhausted (300/min) — honour Retry-After (Error)

Schemas

The shapes the operations above return.

Error

Field	Type	Description
error	object
error.code	string
error.message	string