v1
latestOpenAPI 3.0.32026-07-264469137.7 KBSubscriptions
List subscriptions
List subscriptions for your organization, newest first. Filter by customer or status.
get/v1/subscriptions
Query parameters
limitinteger
offsetinteger
customer_idstring
Only subscriptions for this customer (cust_...).
status'trialing' | 'active' | 'past_due' | 'unpaid' | 'canceled'
Only subscriptions in this status.
Response
A page of subscriptions
Example response
{
"items": [
{
"id": "sub_1a2b3c4d5e6f",
"customer": {
"customer_id": "cust_xyz789",
"email": "jane@example.com",
"name": "Jane Doe",
"phone_number": "+2348012345678",
"metadata": {
"plan": "pro"
},
"created_at": "2026-01-24T12:00:00.000Z",
"updated_at": "2026-01-24T12:00:00.000Z"
},
"payment_method_id": "pm_7h8i9j0k",
"status": "active",
"collection_method": "charge_automatically",
"currency": "USD",
"amount": "10.00",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"quantity": 1,
"current_period_start": "2026-04-01T00:00:00Z",
"current_period_end": "2026-05-01T00:00:00Z",
"previously_billed_at": "2026-04-01T00:00:00Z",
"next_billed_at": "2026-05-01T00:00:00Z",
"trial_end": "2026-04-15T00:00:00Z",
"created_at": "2026-03-01T12:00:00Z",
"product": {
"id": "prod_abc123",
"name": "Pro plan",
"description": "Everything in Basic, plus priority support.",
"status": "active",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"trial_period": {
"interval": "day",
"frequency": 14
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-03-01T12:00:00Z"
},
"items": [
{
"id": "si_11aa22bb",
"status": "active",
"quantity": 1,
"recurring": true,
"price_type": "fixed",
"unit_amount": "10.00",
"currency": "USD",
"previously_billed_at": "2026-04-01T00:00:00Z",
"next_billed_at": "2026-05-01T00:00:00Z",
"price": {
"id": "price_pro_usd",
"product_id": "prod_abc123",
"price_type": "fixed",
"currency": "USD",
"unit_amount": "10.00",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"trial_period": {
"interval": "day",
"frequency": 14
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-03-01T12:00:00Z"
},
"product": {
"id": "prod_abc123",
"name": "Pro plan",
"description": "Everything in Basic, plus priority support.",
"status": "active",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"trial_period": {
"interval": "day",
"frequency": 14
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-03-01T12:00:00Z"
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}
],
"metadata": {
"plan": "pro",
"seat_count": "5"
}
}
],
"pagination": {
"next_cursor": "cur_50",
"has_more": true,
"limit": 50,
"returned": 50,
"total": 137
}
}