Skip to main content
GET
List Subscriptions

Overview

Returns a page of your subscriptions. Use it to reconcile your own records, find a customer’s subscription, or list the ones about to end.
Each item is a Subscription object. All amounts are in cents.

Authentication

This endpoint requires your Secret API Key (server-side only). See Authentication for details.

Query Parameters

string
Filter by status: active, past_due, canceled, or canceling — subscriptions not canceled yet but scheduled to end at current_period_end (cancel_at_period_end: true). Any other value is ignored.active also returns subscriptions scheduled to end (they stay active until then), and canceling covers both active and past_due subscriptions scheduled to end.
Case-insensitive partial match on the subscription ID, customer, customer email or order_id (first 100 characters used).
string
Exact customer identifier, as passed in customer when creating the signup session.
integer
default:"1"
Page number, starting at 1.
integer
default:"20"
Results per page, up to 100.
string
default:"created_at"
created_at, current_period_end, amount (your price) or unit_amount (what the customer pays). Any other value falls back to created_at.
string
default:"desc"
desc or asc.

Response Fields

array
required
Subscriptions of this page. See the Subscription object.
integer
required
Number of subscriptions matching the filters, across all pages.
integer
required
Current page.
integer
required
Page size actually applied.

Example Requests

Example Response

Authorizations

Authorization
string
header
required

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

Query Parameters

status
enum<string>

Filter by status. canceling = not canceled yet but scheduled to end at current_period_end (cancel_at_period_end: true). Other values are ignored.

Available options:
active,
past_due,
canceled,
canceling

Case-insensitive partial match on subscription ID, customer, customer email or order_id

Maximum string length: 100
customer
string

Exact customer identifier, as passed when creating the signup session

page
integer
default:1
Required range: x >= 1
per_page
integer
default:20

Results per page (capped at 100)

Required range: 1 <= x <= 100
sort_by
enum<string>
default:created_at
Available options:
created_at,
current_period_end,
amount,
unit_amount
sort_order
enum<string>
default:desc
Available options:
desc,
asc

Response

Subscriptions retrieved successfully

data
object[]
total
integer

Number of subscriptions matching the filters

page
integer
per_page
integer