Skip to content
Docs
APISign inStart free

List subscriptions

The subscriptions.list operation: GET /api/v1/subscriptions in the REST API and the subscriptions_list tool in the MCP server.

GET/api/v1/subscriptions

Lists the brand's subscriptions in the request's mode, newest first. Filter by customerId, status (trialing, active, past_due, unpaid, paused, canceled, incomplete or incomplete_expired) or priceId (subscriptions with an item on that price).

Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

At a glance

  • REST: GET /api/v1/subscriptions
  • MCP tool: subscriptions_list
  • Operation ID: subscriptions.list
  • Scope: Brand
  • Permission: subscriptions:read
  • Risk tier: read
  • Dry run: Not supported
  • Idempotency: Not needed (read only)
  • Modes: Test and live
  • Pagination: limit (at most 100) and starting_after
  • Authentication: API key with the subscriptions:read scope
  • Since: M5

Request

Query parameters

FieldTypeRequiredDescription
customerIdcus_… IDNoOnly this customer's subscriptions.
statusone of incomplete, incomplete_expired, trialing, active, past_due, unpaid, paused, canceledNoOnly subscriptions in this status.
priceIdprice_… IDNoOnly subscriptions with an item on this price.
limitinteger (1 to 100)No
starting_aftersub_… IDNo

Response

200 OK with a JSON object, a page of the list (newest first):

FieldTypeDescription
object"list"
dataarray of object
data[].idsub_… ID
data[].object"subscription"
data[].livemodeboolean
data[].entityIdent_… ID
data[].brandIdbrd_… ID
data[].customerIdcus_… ID
data[].statusone of incomplete, incomplete_expired, trialing, active, past_due, unpaid, paused, canceledincomplete (waiting for the first payment, 23 hours), trialing, active, past_due, unpaid, paused, canceled or incomplete_expired (spec §16.1).
data[].itemsarray of object
data[].items[].idsi_… ID
data[].items[].priceIdprice_… ID
data[].items[].productIdprod_… ID
data[].items[].quantityinteger
data[].items[].createdAtdate-time
data[].currencystring
data[].mrrmoney or nullThe items' monthly recurring amount (licensed items, before discounts and tax).
data[].collectionMethodone of charge_automatically, send_invoice
data[].daysUntilDueinteger or null
data[].defaultPaymentMethodIdpm_… ID or null
data[].billingCycleAnchordate-time
data[].currentPeriodStartdate-time
data[].currentPeriodEnddate-time
data[].trialStartdate-time or null
data[].trialEnddate-time or null
data[].trialEndBehaviorone of convert, cancel_if_no_payment_method, pause_if_no_payment_method
data[].cancelAtPeriodEndboolean
data[].cancelAtdate-time or null
data[].canceledAtdate-time or null
data[].endedAtdate-time or null
data[].cancellationobject or null
data[].pauseobject or null
data[].discountIdsarray of disc_… ID
data[].pendingUpdateobject or null
data[].latestInvoiceIdinv_… ID or null
data[].incompleteExpiresAtdate-time or null
data[].testClockIdclk_… ID or null
data[].dunningobject or nullDunning (§16.10) while past due or unpaid; null otherwise.
data[].usageThresholdmoney or nullUnbilled metered usage worth this much is invoiced at once (spec §16.7).
data[].entitlementGraceUntildate-time or null
data[].metadataobject
data[].versioninteger
data[].createdAtdate-time
data[].updatedAtdate-time
has_moreboolean
next_cursorsub_… ID or null

Examples

A customer's subscriptions

HTTP
GET /api/v1/subscriptions?customerId=cus_01m4tx5nj8emwbyf7y9vcf47z4
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "sub_01m4tx5nj8emwbyf7y9vcf47z5",
      "object": "subscription",
      "livemode": false,
      "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47zm",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47z4",
      "status": "active",
      "items": [
        {
          "id": "si_01m4tx5nj8emwbyf7y9vcf47za",
          "priceId": "price_01m4tx5nj8emwbyf7y9vcf47y2",
          "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
          "quantity": 3,
          "createdAt": "2026-10-13T12:00:00.000Z"
        },
        {
          "id": "si_01m4tx5nj8emwbyf7y9vcf47zb",
          "priceId": "price_01m4tx5nj8emwbyf7y9vcf47y9",
          "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y1",
          "quantity": 1,
          "createdAt": "2026-10-13T12:00:00.000Z"
        }
      ],
      "currency": "EUR",
      "mrr": {
        "amount": "87000000",
        "currency": "EUR"
      },
      "collectionMethod": "charge_automatically",
      "daysUntilDue": null,
      "defaultPaymentMethodId": "pm_01m4tx5nj8emwbyf7y9vcf47zd",
      "billingCycleAnchor": "2026-10-13T12:00:00.000Z",
      "currentPeriodStart": "2026-10-13T12:00:00.000Z",
      "currentPeriodEnd": "2026-11-13T12:00:00.000Z",
      "trialStart": null,
      "trialEnd": null,
      "trialEndBehavior": "convert",
      "cancelAtPeriodEnd": false,
      "cancelAt": null,
      "canceledAt": null,
      "endedAt": null,
      "cancellation": null,
      "pause": null,
      "discountIds": [],
      "pendingUpdate": null,
      "latestInvoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47zn",
      "incompleteExpiresAt": null,
      "testClockId": null,
      "dunning": null,
      "usageThreshold": null,
      "entitlementGraceUntil": null,
      "metadata": {
        "crm_account": "A-1042"
      },
      "version": 2,
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

CodeHTTP statusWhenWhat to do
validation_failed400A filter or pagination value is malformed.Fix the fields listed in details.issues and send the request again.
permission_denied403You can't see this brand's subscriptions (subscriptions:read).Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.