Subscriptions
List Subscriptions
List all subscriptions with pagination and filtering.
GET
List Subscriptions
Intro
Retrieve every subscription created against your products, with filtering by status or product and standard pagination. This is the endpoint to reach for when you need a dashboard view or a periodic sync of subscription state, rather than a lookup on one record.Context
This is one of three subscription endpoints in the Partner API, alongside Get Subscription and Cancel Subscription. Subscriptions themselves are created indirectly — by addingsubscription_frequency_key to a charge or session request — not through this API; see Subscriptions for how recurring billing is set up and billed. This endpoint only reads.
Results are always scoped to the merchant your API key belongs to, and to that key’s environment: a sandbox key only ever sees sandbox subscriptions, a live key only live ones. A subscription created against one of your products never appears for another merchant, regardless of who queries.
Hows
GET /subscriptions
Query parameters
Response
product and customer are null if the linked record can’t be resolved. price is the recurring charge amount in minor units, in currency. trial is always present — is_on_trial is false and the date fields are null for subscriptions that never had a trial.
Errors
Whys
Filtering happens server-side against your product list rather than requiring you to pass merchant identifiers — the API key already carries that scope, soproduct_id only needs to identify which of your products, and ownership is checked before it’s used in the query. This is also why an unrecognized product_id returns 404 PRODUCT_NOT_FOUND instead of an empty list: a filter on someone else’s product should look like it doesn’t exist, not like it matched nothing.
Responses for this endpoint are cached briefly server-side, which is why a subscription’s status can lag a few minutes behind a change made through the dashboard or a webhook-driven update. This trades a small amount of staleness for materially lower load on a query that’s easy to poll aggressively.
Why nots
- This endpoint doesn’t return payment history or trial timelines beyond the summary
trialblock — use Get Subscription for the full record, includingpayment_historyand plan snapshot. - There’s no full-text or customer-email search; filtering is limited to
statusandproduct_id. If you need to find a specific customer’s subscriptions by email, resolve the customer first and filter client-side, or page through with a tightproduct_id. - Don’t rely on this list to reflect a cancellation the instant it happens — given the short cache window, a status change from Cancel Subscription may not show up here for a few minutes even though the cancellation itself already took effect.