Get subscriptions list

📘
API Refs

Staging: List subscriptions

Request parameters

Name	Type	Description	Required
limit	number	Maximum number of subscriptions to return (default: 20, max: 100)	no
starting_after	string	Cursor for pagination - ID of the last subscription from previous page	no
status	string	Filter by subscription status (see enum values below)	no
customer_id	string	Filter by Stripe customer ID (must start with "cus_")	no

Status Filter Values

incomplete
incomplete_expired
trialing
active
past_due
canceled
unpaid
paused
unpaid_paused

Response body

Success Response (200 OK)

Field	Type	Description
data	array	List of subscription objects
pagination	object	Pagination information

Subscription Object Structure

Field	Type	Description
id	string	Subscription ID
status	string	Current subscription status
customer	object	Customer information
plan	object	Plan information
currentPeriodStart	string	Current billing period start (ISO 8601)
currentPeriodEnd	string	Current billing period end (ISO 8601)
createdAt	string	Subscription creation date (ISO 8601)

Customer Object Structure

Field	Type	Description
stripeCustomerId	string	Stripe customer ID
email	string	Customer email
name	string	Customer name

Plan Object Structure

Field	Type	Description
stripePriceId	string	Stripe price ID
name	string	Plan name
amount	number	Plan amount in cents
currency	string	Currency code
interval	string	Billing interval
intervalCount	number	Billing interval count

Pagination Object Structure

Field	Type	Description
limit	number	Applied limit per page
hasMore	boolean	Whether more results are available
nextCursor	string	Cursor for next page (if hasMore is true)

Response

{
  "data": [
    {
      "id": "sub_ExampleSubscription789",
      "status": "active",
      "customer": {
        "stripeCustomerId": "cus_ExampleCustomerID123",
        "email": "[email protected]",
        "name": "John Doe"
      },
      "plan": {
        "stripePriceId": "price_ExamplePriceID456",
        "name": "Premium Auto Insurance",
        "amount": 4999,
        "currency": "usd",
        "interval": "month",
        "intervalCount": 1
      },
      "currentPeriodStart": "2024-01-01T00:00:00.000Z",
      "currentPeriodEnd": "2024-02-01T00:00:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "hasMore": true,
    "nextCursor": "sub_ExampleSubscription789"
  }
}

Pagination Usage

To retrieve the next page of results, use the nextCursor value from the pagination object as the starting_after parameter:

GET /api/public/subscriptions?limit=10&starting_after=sub_ExampleSubscription789

Error Responses

400 Bad Request: Invalid pagination parameters or filter values
401 Unauthorized: Invalid or missing authorization token
403 Forbidden: Insufficient permissions

Notes

Default Limit: If not specified, the API returns 20 subscriptions per page
Maximum Limit: You cannot retrieve more than 100 subscriptions in a single request
Cursor-based Pagination: Uses cursor-based pagination for consistent results
Filtering: Multiple filters can be combined (e.g., filter by both status and customer_id)
Sorting: Results are returned in descending order by creation date