List subscription contracts
GET /subscriptions/contracts| Scope | subscriptions:read |
| Customer session token | Not accepted: call from your server with an API key |
| Rate limit class | read (limits) |
| Idempotency key | Not used |
| MCP tool | charm_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).
Parameters
Section titled “Parameters”| Name | In | Type | Description |
|---|---|---|---|
limit (optional) | query | integer | Page size, 1–250. Defaults to 50. |
cursor (optional) | query | string | Opaque cursor from a previous response’s next_cursor. |
status (optional) | query | string: ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED | Only contracts in this status. |
plan_id (optional) | query | string | Only contracts bought with this plan. |
customer_id (optional) | query | string | Customer GID or numeric id. |
failed (optional) | query | string: true | true: only contracts whose last payment attempt failed. |
Response 200
Section titled “Response 200”Returns SubscriptionContractList.
| Field | Type | Description |
|---|---|---|
data | array of SubscriptionContract | |
next_cursor | string or null | Pass as cursor to fetch the next page; null on the last page. (nullable) |
has_more | boolean | True 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}Example
Section titled “Example”curl -X GET "https://charm.appfleece.app/api/v1/subscriptions/contracts" \ -H "Authorization: Bearer chrm_live_..."Errors
Section titled “Errors”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.