# List subscriptions > The subscriptions.list operation: GET /api/v1/subscriptions in the REST API and the subscriptions_list tool in the MCP server. 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 | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `customerId` | `cus_…` ID | No | Only this customer's subscriptions. | | `status` | one of `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled` | No | Only subscriptions in this status. | | `priceId` | `price_…` ID | No | Only subscriptions with an item on this price. | | `limit` | integer (1 to 100) | No | | | `starting_after` | `sub_…` ID | No | | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `sub_…` ID | | | `data[].object` | `"subscription"` | | | `data[].livemode` | boolean | | | `data[].entityId` | `ent_…` ID | | | `data[].brandId` | `brd_…` ID | | | `data[].customerId` | `cus_…` ID | | | `data[].status` | one of `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled` | `incomplete` (waiting for the first payment, 23 hours), `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled` or `incomplete_expired` (spec §16.1). | | `data[].items` | array of object | | | `data[].items[].id` | `si_…` ID | | | `data[].items[].priceId` | `price_…` ID | | | `data[].items[].productId` | `prod_…` ID | | | `data[].items[].quantity` | integer | | | `data[].items[].createdAt` | date-time | | | `data[].currency` | string | | | `data[].mrr` | money or null | The items' monthly recurring amount (licensed items, before discounts and tax). | | `data[].collectionMethod` | one of `charge_automatically`, `send_invoice` | | | `data[].daysUntilDue` | integer or null | | | `data[].defaultPaymentMethodId` | `pm_…` ID or null | | | `data[].billingCycleAnchor` | date-time | | | `data[].currentPeriodStart` | date-time | | | `data[].currentPeriodEnd` | date-time | | | `data[].trialStart` | date-time or null | | | `data[].trialEnd` | date-time or null | | | `data[].trialEndBehavior` | one of `convert`, `cancel_if_no_payment_method`, `pause_if_no_payment_method` | | | `data[].cancelAtPeriodEnd` | boolean | | | `data[].cancelAt` | date-time or null | | | `data[].canceledAt` | date-time or null | | | `data[].endedAt` | date-time or null | | | `data[].cancellation` | object or null | | | `data[].pause` | object or null | | | `data[].discountIds` | array of `disc_…` ID | | | `data[].pendingUpdate` | object or null | | | `data[].latestInvoiceId` | `inv_…` ID or null | | | `data[].incompleteExpiresAt` | date-time or null | | | `data[].testClockId` | `clk_…` ID or null | | | `data[].dunning` | object or null | Dunning (§16.10) while past due or unpaid; null otherwise. | | `data[].usageThreshold` | money or null | Unbilled metered usage worth this much is invoiced at once (spec §16.7). | | `data[].entitlementGraceUntil` | date-time or null | | | `data[].metadata` | object | | | `data[].version` | integer | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `sub_…` 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 | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is malformed. | Fix the fields listed in `details.issues` and send the request again. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You 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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).