Get a subscription contract
GET /subscriptions/contracts/{contract_id}| 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_get_subscription_contract |
Parameters
Section titled “Parameters”| Name | In | Type | Description |
|---|---|---|---|
contract_id | path | string | Subscription contract GID (percent-encoded) or its numeric id, as GET /subscriptions/contracts lists it. |
Response 200
Section titled “Response 200”Returns SubscriptionContract.
| Field | Type | Description |
|---|---|---|
id | string | Subscription contract GID. |
numeric_id | string | The contract’s numeric id, usable in every {contract_id} path. |
status | string or null | ACTIVE, PAUSED, CANCELLED, EXPIRED or FAILED. (nullable) |
customer | object | |
plan_id | string or null | The subscription plan the contract was bought with; null for a paid membership. (nullable) |
program_id | string or null | The membership programme; null for a product subscription. (nullable) |
frequency | object or null | (nullable) |
currency | string or null | (nullable) |
per_cycle_total | number | Σ discounted line price × quantity per delivery, shipping excluded. |
lines | array of SubscriptionLine | |
delivery | object or null | (nullable) |
payment_method | object or null | (nullable) |
next_cycle | object or null | (nullable) |
cycles | array of SubscriptionCycle | |
last_attempt | object or null | (nullable) |
last_order_id | string or null | (nullable) |
cancel_reason | string or null | Given when the contract was cancelled through Charm. (nullable) |
note | string or null | The merchant’s internal note. (nullable) |
created_at | string or null | (nullable) |
cancelled_at | string or null | (nullable) |
paused_at | string or null | (nullable) |
updated_at | string or null | (nullable) |
{ "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": "unit", "count": 1 }, "currency": "EUR", "per_cycle_total": 1, "lines": [ { "id": "id", "product_id": "8123456789", "variant_id": "44123456789", "selling_plan_id": "selling plan id", "title": "title", "variant_title": "variant title", "sku": "sku", "quantity": 1, "price": 1, "discounted_price": 1 } ], "delivery": { "type": "earn", "city": "city", "country": "country", "zip": "zip", "option": "option", "price": 1 }, "payment_method": { "id": "id", "brand": "brand", "last_digits": "last digits", "expiry_month": 1, "expiry_year": 1 }, "next_cycle": { "index": 1, "expected_at": "2026-10-01T09:30:00.000Z" }, "cycles": [ { "index": 1, "expected_at": "2026-10-01T09:30:00.000Z", "status": "active", "skipped": false, "forgiven": false, "order_id": "order id" } ], "last_attempt": { "state": "state", "error_code": "error code", "cycle_index": 1, "at": "2026-10-01T09:30:00.000Z" }, "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"}Example
Section titled “Example”curl -X GET "https://charm.appfleece.app/api/v1/subscriptions/contracts/<contract_id>" \ -H "Authorization: Bearer chrm_live_..."Errors
Section titled “Errors”unauthorized · invalid_token · insufficient_scope · access_required · not_found · 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.