Subscriptions
Get Subscription
Get details of a specific subscription.
GET
Get Subscription
Intro
Retrieve the full record for a single subscription — billing state, trial info, plan snapshot, and payment history — by its ID. Use this when you already have asubscription_id (from a webhook, from List Subscriptions, or stored from creation) and need the current, uncached state of that one record.
Context
This sits alongside List Subscriptions and Cancel Subscription as one of the three subscription-management endpoints in the Partner API. Subscriptions are created by addingsubscription_frequency_key to a charge or checkout session, not through this endpoint — see Subscriptions for that flow and for how billing frequencies and renewals work.
Unlike the list endpoint, this call always reads the database directly, so it reflects any change immediately — including one made seconds ago through Cancel Subscription.
Hows
GET /subscriptions/{subscription_id}
Path parameters
Response
status is one of pending, active, due, cancelled, paused. price and currency describe the recurring charge; plan is a snapshot of the plan’s key, display name, and features as they were at the time the subscription was created, so it won’t change if you edit the plan later. payment_history entries are { time, amount }, with time as a Unix millisecond timestamp and amount in minor units. cancellation_date is only set once the subscription has been cancelled.
Errors
Whys
A subscription you don’t own and a subscription that doesn’t exist return the identical404 SUBSCRIPTION_PLAN_NOT_FOUND — the API never confirms that an ID is valid but belongs to someone else. That’s deliberate: leaking “this ID is real, just not yours” is a way to enumerate other merchants’ subscription IDs over time.
The same logic applies to environment: a sandbox key requesting a live subscription’s ID gets a 404, not a 400 “wrong environment” error, again so the response can’t be used to distinguish “doesn’t exist” from “exists in the other mode.”
Why nots
- This endpoint doesn’t accept any body or query parameters to shape the response — you get the full record every time. If you only need a handful of fields across many subscriptions, List Subscriptions is the cheaper call.
- It’s read-only. To end a subscription, use Cancel Subscription — there’s no way to change status, price, or frequency through this endpoint.
payment_historyis whatever has accumulated on the record; it isn’t a paginated ledger, so a very long-lived subscription’s history returns in full on every call.