Sample - Stripe API
GET/v1/subscriptions

List subscriptions

Lists subscriptions using filters for customer, account, status, collection method, price, automatic tax, test clock, and lifecycle dates. By default, returns subscriptions that have not been canceled; pass status=canceled to include canceled subscriptions. Use cursor parameters and limit to paginate the results.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

14 parameters
automatic_taxobjectoptional
Filter subscriptions by automatic tax settings. The filter requires the `enabled` field.
collection_methodstringoptional
Filter by collection method: charge_automatically or send_invoice.
Allowed:charge_automaticallysend_invoice
createdobjectoptional
Filter subscriptions created during the specified Unix timestamp or timestamp range.
current_period_endobjectoptional
Filter subscriptions whose minimum item period end falls within the specified Unix timestamp or timestamp range.
current_period_startobjectoptional
Filter subscriptions whose maximum item period start falls within the specified Unix timestamp or timestamp range.
customerstringoptional
Filter by the customer identifier. Subscriptions associated with a test clock are excluded when this and `test_clock` are omitted. Must be no longer than 5000 characters.
customer_accountstringoptional
Filter by the account identifier representing the customer. Must be no longer than 5000 characters.
ending_beforestringoptional
Cursor object identifier used to retrieve the page before the specified item. Must be no longer than 5000 characters.
expandarray<string>optional
Fields to expand in each returned subscription. Each field name must be no longer than 5000 characters.
limitintegeroptional
Maximum number of subscriptions to return. Must be between 1 and 100. Defaults to 10 when omitted.
pricestringoptional
Filter for subscriptions containing the specified recurring price identifier. Must be no longer than 5000 characters.
starting_afterstringoptional
Cursor object identifier used to retrieve the page after the specified item. Must be no longer than 5000 characters.
statusstringoptional
Filter by subscription status: active, all, canceled, ended, incomplete, incomplete_expired, past_due, paused, trialing, or unpaid. Defaults to subscriptions that have not been canceled when omitted.
Allowed:activeallcanceledendedincompleteincomplete_expiredpast_duepausedtrialingunpaid
test_clockstringoptional
Filter for subscriptions associated with the specified test clock. Must be no longer than 5000 characters.

2 status codes
200Returns a paginated list object containing subscriptions, the list URL, the object type, and a `has_more` indicator.
dataarray<Subscription>required
has_morebooleanrequired
True if this list has another page of items after this one that can be fetched.
objectstringrequired
String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
Allowed:list
urlstringrequired
The URL where this list can be accessed.
defaultError response.
errorobjectrequired

Error handling

status must be one of active, all, canceled, ended, incomplete, incomplete_expired, past_due, paused, trialing, or unpaid. The automatic_tax filter requires enabled, and limit must be between 1 and 100 with a default of 10 when omitted. Date filters accept Unix timestamps or timestamp ranges, while cursor values must identify subscription objects.