API ReferenceSubscriptions

List Subscriptions

View as Markdown
List subscriptions for an account with pagination. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency. Query parameters: - customer ID: Optional filter by customer ID - state: Optional filter by subscription state - split_from_subscription: Optional filter to find subscriptions that were split from a given parent subscription ID (used to locate the successor after a cross-interval plan change). - next_invoice_only: Optional flag — opt-in exclusion of subscriptions whose `current_period_end` does not predict an actual invoice (see parameter doc for details). The business portal "Next Invoice" filter passes this; public-API consumers default to historical behaviour. - Standard pagination params: limit, offset, sortBy, sortOrder, filter, search

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Query parameters

customer_external_idstring or nullOptional
stateenum or nullOptional
The possible states of a subscription. Most are self-explanatory: it starts INCOMPLETE (created, not yet paid for), or TRIALING / SCHEDULED, becomes ACTIVE once paid, and can end up PAUSED, PAST_DUE (a payment failed), or CANCELLED. ACTIVE_UNSETTLED is the unusual one, added for slow bank rails like SEPA where the money does not arrive until days later. It means: "we already let the customer in at checkout, but their payment has not actually settled yet." A subscription is created straight into this state -- nothing ever moves INTO it from another state. It has exactly two ways out: it becomes ACTIVE if the payment settles, or CANCELLED if the payment fails, times out, or is later reversed (a chargeback).
split_from_subscription_external_idstring or nullOptional
next_invoice_onlybooleanOptionalDefaults to false
When true, only subscriptions whose `current_period_end` represents an upcoming invoice are returned. Excludes cancelled subscriptions, paused subscriptions, and active subscriptions set to cancel at period end (`cancel_at_period_end=true`) — none of these will produce another invoice on their `current_period_end` date. Intended for callers filtering by `current_period_end` to answer 'what bills next?'. Default `false` preserves the historical behaviour of returning every matching subscription regardless of state.
expandlist of strings or nullOptional
limitintegerOptional1-100Defaults to 50
Number of items per page
offsetintegerOptional>=0Defaults to 0
Number of items to skip
filterstringOptionalDefaults to {}

Filter conditions as key-value pairs or advanced filter objects (JSON string)

sortBystring or nullOptional
Field to sort by
sortOrderintegerOptionalDefaults to -1

Sort order: 1 for ascending, -1 for descending

searchstring or nullOptional

Keyword-based search across multiple fields

Response

Successful Response
itemslist of objects
totalinteger
has_moreboolean

Errors

422
Unprocessable Entity Error