List Subscriptions

Retrieve a paginated list of subscriptions. Supports filtering by customer, plan, and status.

GET /v1/subscriptions

List Subscriptions

cURL

curl --request GET \
  --url https://api.example.com/v1/subscriptions

200

{
  "data": [
    {
      "id": "<string>",
      "customer_id": "<string>",
      "plan_id": "<string>",
      "subscription_status": "<string>",
      "currency": "<string>",
      "billing_cadence": "<string>",
      "billing_period": "<string>",
      "start_date": "<string>",
      "current_period_start": "<string>",
      "current_period_end": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123,
  "has_more": true
}

Query Parameters

limit · integer · default: "10"

Maximum number of subscriptions to return.

Example: 20

offset · integer · default: "0"

Number of subscriptions to skip before starting to return results.

Example: 10

cursor · string

Cursor for pagination (alternative to offset).

customer_id · string

Filter by customer ID.

Example: "cust_a1b2c3d4e5f6g7h8i9j0"

plan_id · string

Filter by plan ID.

Example: "plan_a1b2c3d4e5f6g7h8i9j0"

subscription_status · string

Filter by subscription status.

Options: "ACTIVE", "CANCELLED", "INCOMPLETE", "EXPIRED", "PAUSED", "DRAFT"

Response

data · array

Array of subscription objects.

Show subscription properties

id · string

Unique identifier for the subscription.

customer_id · string

FlexPrice customer ID.

plan_id · string

Plan ID.

subscription_status · string

Current subscription status.

currency · string

Currency code.

billing_cadence · string

Billing frequency.

billing_period · string

Billing period unit.

start_date · string

ISO 8601 timestamp when subscription starts.

current_period_start · string

ISO 8601 timestamp of current billing period start.

current_period_end · string

ISO 8601 timestamp of current billing period end.

created_at · string

ISO 8601 timestamp when the subscription was created.

updated_at · string

ISO 8601 timestamp when the subscription was last updated.

total · integer

Total number of subscriptions matching the query.

limit · integer

Maximum number of results returned.

offset · integer

Number of results skipped.

has_more · boolean

Whether there are more results available.

Example Request

cURL

curl --request GET \
  --url 'https://api.flexprice.io/v1/subscriptions?limit=20&customer_id=cust_a1b2c3d4e5f6g7h8i9j0' \
  --header 'Authorization: Bearer <token>'

Example Response

{
  "data": [
    {
      "id": "sub_x1y2z3a4b5c6d7e8f9g0",
      "customer_id": "cust_a1b2c3d4e5f6g7h8i9j0",
      "plan_id": "plan_a1b2c3d4e5f6g7h8i9j0",
      "subscription_status": "ACTIVE",
      "currency": "usd",
      "billing_cadence": "IN_ADVANCE",
      "billing_period": "MONTH",
      "billing_period_count": 1,
      "start_date": "2024-03-20T00:00:00Z",
      "current_period_start": "2024-03-20T00:00:00Z",
      "current_period_end": "2024-04-20T00:00:00Z",
      "created_at": "2024-03-20T15:04:05Z",
      "updated_at": "2024-03-20T15:04:05Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "has_more": false
}