Skip to main content
GET
List Subscriptions

Authorizations

Authorization
string
header
required

Use a Bearer token to access this API.

Query Parameters

customer
string | null

Filter by customer ID.

Example:

"fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA"

expand_customer
boolean | null

If true, expands the customer object in the response.

Example:

false

starting_after
string | null

A cursor for use in pagination. starting_after is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, ending with fsub_xyz, your subsequent call can include starting_after=fsub_xyz to fetch the next page.

Example:

"fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA"

ending_before
string | null

A cursor for use in pagination. ending_before is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, starting with fsub_abc, your subsequent call can include ending_before=fsub_abc to fetch the previous page.

Example:

"fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA"

status
enum<string> | null

Filter by subscription status.

Available options:
incomplete,
incomplete_expired,
trialing,
active,
past_due,
canceled,
unpaid,
paused
Example:

"incomplete"

offset
integer<int32> | null

Number of objects to skip before returning results.

Required range: x >= 0
Example:

3

limit
integer<int32> | null

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Required range: x >= 0
Example:

10

expand
string
default:""

Comma-separated list of related objects to expand in the response.

Supported keys: customer; latest_invoice (alias invoice); payment_method; price (alias product); and discounts. Combine discounts with coupons (expand=discounts,coupons) to hydrate each discount's nested source.coupon into a full object instead of a bare ID.

Unrecognized keys are ignored rather than rejected: a misspelled or guessed key (e.g. coupon) returns the same response as no expand at all, with no error.

Response

An envelope wrapping a list of subscription objects.

An envelope wrapping a list of subscription objects.

subscriptions
object[]
required

The list of subscriptions.