Retrieve a subscription
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.
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.
Authorization
secretKey Your secret key: sk_live_… or sk_test_….
In: header
Path Parameters
The subscription's id, which starts with sub_.
^sub_[0-9a-f]{32}$Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/subscriptions/sub_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c"{ "object": "subscription", "subscription_id": "sub_4e8f1a6b2c7d3e9f0a5b1c6d2e7f3a8b", "status": "active", "product_id": "pdt_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f", "name": "Pro plan", "quantity": 1, "recurring_amount": 9900, "currency": "AED", "billing_interval": "month", "interval_count": 1, "customer": { "customer_id": "cus_2c4e6a8b0d1f4a3c5e7b9d1f3a5c7e9b", "name": "Nour Al Abbas", "email": "nour.alabbas@example.com" }, "payment_method": { "brand": "visa", "last4": "4242", "exp_month": 4, "exp_year": 2029 }, "current_period_start": "2026-09-01T10:00:00.000Z", "next_billing_date": "2026-10-01T10:00:00.000Z", "cancel_at_period_end": false, "cancelled_at": null, "cancellation_reason": null, "failed_payment_attempts": 0, "next_retry_at": null, "checkout_session_id": "cks_1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c", "metadata": {}, "livemode": true, "created_at": "2026-08-01T10:00:00.000Z"}Refund a payment POST
Gives back all that is left of a succeeded payment, or `amount` of it in the payment's minor unit, to the card it was paid with. Answers the payment once the refund is recorded: `status` is `refunded` or `partially_refunded` and `refunded_amount` has grown, and a `refund.succeeded` event goes out. Utopia's fee is not returned, so `net_amount` can fall below zero. A live refund is drawn on your balance in the payment's currency and is refused while that balance does not cover it (`409 INSUFFICIENT_BALANCE`). More than what is left of the payment is refused (`400 AMOUNT_TOO_LARGE`), as is a payment that has not succeeded or is refunded already (`409 NOT_REFUNDABLE`, `ALREADY_REFUNDED`). Some payments can be refunded only in full: one charged in the customer's own currency (`409 FULL_REFUND_ONLY`), and some payments made today, until they settle overnight (`409 NOT_SETTLED`; a full refund is possible at once). When the card processor cannot be reached the refund is not made (`502 REFUND_FAILED`); try again later. The card holder usually sees the money back within a few working days, depending on their bank. Send `Idempotency-Key` so a retried request does not refund twice.
List subscriptions GET
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.