API ReferenceSubscriptions

List Subscriptions By Customer

View as Markdown
Get all subscriptions for a specific customer. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency. Path parameters: - customer ID: The customer's ID Query parameters: - state: Optional filter by subscription state

Authentication

AuthorizationBearer

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

Path parameters

customer_external_idstringRequired
account_idstringRequired

Query parameters

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).
expandlist of strings or nullOptional

Response

Successful Response
idstring
stateenum

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).

currencyenum
ISO 4217 currency codes.
descriptionstring or null
current_period_startdatetime
current_period_enddatetime
trial_startdatetime or null
trial_enddatetime or null
created_atdatetime
updated_atdatetime
itemslist of objects
customerobject
collection_methodenum
payment_methodobject or null
Payment method API response model.
billing_intervalstring or nullOptional
billing_interval_countinteger or nullOptional
paused_atdatetime or nullOptional
resumes_atdatetime or nullOptional
pause_at_endboolean or nullOptional
cancel_at_period_endboolean or nullOptional
cancel_atdatetime or nullOptional
cancellation_refund_optionenum or nullOptional

Refund options when cancelling a subscription.

  • NONE: Cancel with no refund (current behavior)
  • FULL: Refund full current period amount
  • PRORATED: Refund unused portion of current period
  • CANCEL_UNPAID: Use dunning_end_behavior for unpaid invoices
cancellation_detailsobject or nullOptional

Details about why a subscription was cancelled.

All fields are optional — callers can provide any combination. Stored as JSONB on the subscription entity.

net_dinteger or nullOptional
statement_descriptor_suffixstring or nullOptional
Statement descriptor suffix for this subscription.
total_billing_cyclesinteger or nullOptional
remaining_billing_cyclesinteger or nullOptional
contract_auto_renewboolean or nullOptional
discountobject or nullOptional
Response schema for discount data.
last_successful_processor_idstring or nullOptional
metadatamap from strings to any or nullOptional
split_from_subscriptionstring or nullOptional

ID of the subscription this was split from (cross-interval plan change).

split_to_subscriptionslist of strings or nullOptional

IDs of subscriptions created from this one (cross-interval plan change).

pending_plan_changeobject or nullOptional
Pending plan change scheduled for period end. Present when a deferred plan change is awaiting execution.
custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

Errors

422
Unprocessable Entity Error