• Pricing
  • Blog
Log inBook a demo
Adjust balance POSTApply an Offer to a subscription PUTCancel subscription POSTChange plan POSTCreate a recovery payment link for a past due subscription POSTCreate subscription POSTGet active subscription GETGet subscription by ID GETList subscriptions GETPreview plan change POSTReactivate a past due or canceled subscription POSTRemove an Offer from a pending checkout DELETETop up balance POSTRevert scheduled cancellation POSTUpdate payment method POST
System status
DocumentationKnowledge BaseBuild with AIAPI ReferenceWebhooks

List subscriptions

List all subscriptions. Filter by customer ID or status.

GET
/subscriptions

List all subscriptions. Filter by customer ID or status.

Authorization

ApiKeyAuth
x-api-key<token>

In: header

Query Parameters

customerId?string
status?string

Value in

  • "draft"
  • "pending_payment"
  • "trialing"
  • "active"
  • "past_due"
  • "canceled"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/subscriptions"
{  "object": "list",  "data": [    {      "id": "string",      "customerId": "string",      "plan": {        "id": "string",        "name": "string"      },      "name": "string",      "description": "string",      "status": "draft",      "billingInterval": "weekly",      "trialEndsAt": "2019-08-24T14:15:22Z",      "currentPeriod": {        "start": "2019-08-24T14:15:22Z",        "end": "2019-08-24T14:15:22Z",        "daysRemaining": 0      },      "cancellation": {        "scheduledAt": "2019-08-24T14:15:22Z",        "reason": "string",        "effectiveAt": "2019-08-24T14:15:22Z"      },      "cancelAtPeriodEnd": true,      "scheduledPlanChange": {        "changeType": "plan_downgrade",        "newPlanId": "string",        "newPlanName": "string",        "newBillingInterval": "string",        "scheduledFor": "2019-08-24T14:15:22Z"      },      "startDate": "2019-08-24T14:15:22Z",      "endDate": "2019-08-24T14:15:22Z",      "billingDayOfMonth": -9007199254740991,      "nextBillingDate": "2019-08-24T14:15:22Z",      "checkoutUrl": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "offerApplications": [        {          "id": "string",          "name": "string",          "appliesTo": {            "type": "plan_price",            "id": "string"          },          "offerId": "string",          "source": "direct",          "status": "quoted",          "currency": "string",          "subtotal": -9007199254740991,          "discountAmount": -9007199254740991,          "total": -9007199254740991,          "phases": [            {              "type": "free_trial",              "durationDays": 1,              "durationInterval": "weekly",              "startsAt": "2019-08-24T14:15:22Z",              "endsAt": "2019-08-24T14:15:22Z"            }          ],          "quotedAt": "2019-08-24T14:15:22Z",          "expiresAt": "2019-08-24T14:15:22Z",          "appliedAt": "2019-08-24T14:15:22Z"        }      ],      "priceId": "string",      "object": "subscription",      "livemode": true    }  ],  "hasMore": true,  "nextCursor": "string"}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

Get subscription by ID GET

Get a subscription by its public ID, regardless of status (including pending_payment and past_due).

Preview plan change POST

Preview proration details for an immediate plan change without applying it. Free-to-paid changes are never scheduled and the change-plan endpoint always returns hosted checkout for them. For paid plans, interval direction takes precedence: a longer interval is immediate and a shorter interval is scheduled. When the interval is unchanged, a higher-sort-order plan is immediate and a lower-sort-order plan is scheduled. A paid-to-free change is always scheduled. Returns credit, charge, and net amount. The target plan must belong to the same plan group as the current plan, otherwise a 400 with code `plans_not_in_same_group` is returned. A change between two free plans has nothing to prorate and returns a zero-amount estimate. Scheduled changes return a 400 with code `plan_change_scheduled`; apply those via the change-plan endpoint. Pass offerId to quote the destination plan with an Offer.