Skip to content

List subscription contracts

GET /subscriptions/contracts
Scopesubscriptions:read
Customer session tokenNot accepted: call from your server with an API key
Rate limit classread (limits)
Idempotency keyNot used
MCP toolcharm_list_subscription_contracts

Every subscription contract Charm owns, newest first, cursor-paginated: product subscriptions (plan_id) and paid memberships (program_id), with lines, delivery, the card on file, the next billing cycle, the known cycles and the last payment attempt. Filter by status, plan_id, customer_id or failed=true (last payment attempt failed).

NameInTypeDescription
limit (optional)queryintegerPage size, 1–250. Defaults to 50.
cursor (optional)querystringOpaque cursor from a previous response’s next_cursor.
status (optional)querystring: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILEDOnly contracts in this status.
plan_id (optional)querystringOnly contracts bought with this plan.
customer_id (optional)querystringCustomer GID or numeric id.
failed (optional)querystring: truetrue: only contracts whose last payment attempt failed.

Returns SubscriptionContractList.

FieldTypeDescription
dataarray of SubscriptionContract
next_cursorstring or nullPass as cursor to fetch the next page; null on the last page. (nullable)
has_morebooleanTrue when another page exists.
{
"data": [
{
"id": "id",
"numeric_id": "numeric id",
"status": "active",
"customer": {
"id": "id",
"email": "shopper@example.com"
},
"plan_id": "plan id",
"program_id": "program id",
"frequency": {
"unit": null,
"count": null
},
"currency": "EUR",
"per_cycle_total": 1,
"lines": [
null
],
"delivery": {
"type": null,
"city": null,
"country": null,
"zip": null,
"option": null,
"price": null
},
"payment_method": {
"id": null,
"brand": null,
"last_digits": null,
"expiry_month": null,
"expiry_year": null
},
"next_cycle": {
"index": null,
"expected_at": null
},
"cycles": [
null
],
"last_attempt": {
"state": null,
"error_code": null,
"cycle_index": null,
"at": null
},
"last_order_id": "last order id",
"cancel_reason": "cancel reason",
"note": "note",
"created_at": "2026-10-01T09:30:00.000Z",
"cancelled_at": "2026-10-01T09:30:00.000Z",
"paused_at": "2026-10-01T09:30:00.000Z",
"updated_at": "2026-10-01T09:30:00.000Z"
}
],
"next_cursor": null,
"has_more": true
}
Terminal window
curl -X GET "https://charm.appfleece.app/api/v1/subscriptions/contracts" \
-H "Authorization: Bearer chrm_live_..."

unauthorized · invalid_token · insufficient_scope · access_required · validation_error · rate_limited

Every error body carries code, message, request_id and a doc_url pointing at the matching entry in the error catalog.