CommetCommet
GitHubDiscordStatus
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 GETPause subscription POSTPreview plan change POSTReactivate a past due or canceled subscription POSTRemove an Offer from a pending checkout DELETEResume subscription POSTRevoke scheduled pause DELETETop up balance POSTRevert scheduled cancellation POSTUpdate payment method POSTUpdate subscription pause PATCH
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"
  • "paused"
  • "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": "sub_1a2b3c4d",      "customerId": "cus_1a2b3c4d",      "plan": {        "id": "plan_1a2b3c4d",        "name": "Pro"      },      "name": "Pro",      "description": null,      "status": "active",      "billingInterval": "monthly",      "trialEndsAt": null,      "currentPeriod": {        "start": "2026-09-07T12:00:00.000Z",        "end": "2026-10-07T12:00:00.000Z",        "daysRemaining": 30      },      "cancellation": null,      "cancelAtPeriodEnd": false,      "scheduledPlanChange": null,      "startDate": "2026-09-07T12:00:00.000Z",      "endDate": null,      "billingDayOfMonth": 7,      "nextBillingDate": "2026-10-07T12:00:00.000Z",      "checkoutUrl": null,      "createdAt": "2026-09-07T12:00:00.000Z",      "updatedAt": "2026-09-07T12:00:00.000Z",      "offerApplications": [],      "pause": null,      "priceId": "price_1a2b3c4d",      "object": "subscription",      "livemode": false    }  ],  "hasMore": false}
{  "error": {    "type": "validation_error",    "code": "validation_error",    "message": "The request contains an invalid parameter.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md"  }}
{  "error": {    "type": "authentication_error",    "code": "unauthorized",    "message": "A valid API key is required.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md"  }}
{  "error": {    "type": "authentication_error",    "code": "forbidden",    "message": "You do not have permission to perform this operation.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md"  }}
{  "error": {    "type": "rate_limit_error",    "code": "rate_limited",    "message": "Too many requests. Retry after the interval specified in the Retry-After header.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md"  }}
{  "error": {    "type": "internal_error",    "code": "internal_error",    "message": "An unexpected error occurred while processing the request.",    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md"  }}

Get subscription by ID GET

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

Pause subscription POST

Pause immediately or schedule a pause for the end of the current billing or trial period. Set durationDays to null for an indefinite pause.