List subscriptions
Lists subscriptions, newest first, filtered by `status` or by customer. One page carries `items`, `has_more` and `next_cursor`; pass `next_cursor` back as `cursor` for the next page. Only subscriptions belonging to the key's merchant and mode are listed.
Lists subscriptions, newest first, filtered by status or by customer. One page carries items, has_more and next_cursor; pass next_cursor back as cursor for the next page. Only subscriptions belonging to the key's merchant and mode are listed.
Authorization
secretKey Your secret key: sk_live_… or sk_test_….
In: header
Query Parameters
How many records to return in one page: 1 to 100, and 20 when left out. Asking for more than 100 is refused with INVALID_REQUEST.
1 <= value <= 10020The next_cursor of the previous page; leave it out for the first page. A cursor marks the record the next page starts after, so records created while you walk the list never shift the pages you have not read yet. Anything the API did not issue is refused with INVALID_CURSOR.
Only subscriptions in this status. active and on_hold are the two that still grant access.
Value in
- "active"
- "on_hold"
- "cancelled"
Only this customer's subscriptions, by cus_ id.
^cus_[0-9a-f]{32}$Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/subscriptions"{ "items": [ { "object": "subscription", "subscription_id": "sub_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "status": "active", "product_id": "pdt_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "name": "string", "quantity": 0, "recurring_amount": 0, "currency": "AED", "billing_interval": "day", "interval_count": 0, "customer": { "customer_id": "cus_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "name": "string", "email": "user@example.com" }, "payment_method": { "brand": "string", "last4": "string", "exp_month": 0, "exp_year": 0 }, "current_period_start": "2019-08-24T14:15:22Z", "next_billing_date": "2019-08-24T14:15:22Z", "cancel_at_period_end": true, "cancelled_at": "2019-08-24T14:15:22Z", "cancellation_reason": "requested", "failed_payment_attempts": 0, "next_retry_at": "2019-08-24T14:15:22Z", "checkout_session_id": "cks_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "metadata": { "property1": "string", "property2": "string" }, "livemode": true, "created_at": "2019-08-24T14:15:22Z" } ], "has_more": true, "next_cursor": "string"}Retrieve a subscription GET
Returns one subscription: its status, what it charges and how often, the card it renews with, when the current period started, when it renews next, and once it has ended, when and why. Grant access while the status is `active` or `on_hold`, and read the subscription after each `subscription.*` event rather than keeping your own copy of the schedule. `next_retry_at` is filled in only while a subscription that Utopia renews is `on_hold`; when the card processor renews it, the processor decides when to retry and this stays null. Only subscriptions belonging to the key's merchant and mode are visible.
Update or cancel a subscription PATCH
Send `{ "status": "cancelled" }` to cancel now, or `{ "cancel_at_period_end": true }` to let the paid period run out without renewing. `metadata` is the only other thing this endpoint changes, and it replaces what was stored. What a subscription charges — its product, amount, currency, interval, quantity and customer — is fixed when it starts: to change any of it, cancel this subscription and take a new checkout. Cancelling cannot be taken back. A subscription the card processor renews is stopped there first, and if the processor does not confirm, nothing changes here and the answer is `502 CANCELLATION_FAILED`. For such a subscription, ending it at the end of the period stops those renewals immediately (the period is paid already), so it cannot be resumed: `cancel_at_period_end: false` afterwards answers `409 CANCELLATION_FINAL`. Changing an already cancelled subscription answers `409 SUBSCRIPTION_CANCELLED`, and a renewal being charged right now answers `409 CHARGE_IN_PROGRESS` — try again in a minute.