# Get a subscription

> The subscriptions.get operation: GET /api/v1/subscriptions/{id} in the REST API and the subscriptions_get tool in the MCP server.

Reads a subscription: its status, items, billing period, trial, cancellation, pause, scheduled change
(`pendingUpdate`), discounts, latest invoice and its items' monthly recurring amount (`mrr`).

## At a glance

- **REST:** `GET /api/v1/subscriptions/{id}`
- **MCP tool:** `subscriptions_get`
- **Operation ID:** `subscriptions.get`
- **Scope:** Brand
- **Permission:** `subscriptions:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `subscriptions:read` scope
- **Since:** M5

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `sub_…` ID |             |

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field                    | Type                                                                                                        | Description                                                                                                                                                    |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | `sub_…` ID                                                                                                  |                                                                                                                                                                |
| `object`                 | `"subscription"`                                                                                            |                                                                                                                                                                |
| `livemode`               | boolean                                                                                                     |                                                                                                                                                                |
| `entityId`               | `ent_…` ID                                                                                                  |                                                                                                                                                                |
| `brandId`                | `brd_…` ID                                                                                                  |                                                                                                                                                                |
| `customerId`             | `cus_…` ID                                                                                                  |                                                                                                                                                                |
| `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). |
| `items`                  | array of object                                                                                             |                                                                                                                                                                |
| `items[].id`             | `si_…` ID                                                                                                   |                                                                                                                                                                |
| `items[].priceId`        | `price_…` ID                                                                                                |                                                                                                                                                                |
| `items[].productId`      | `prod_…` ID                                                                                                 |                                                                                                                                                                |
| `items[].quantity`       | integer                                                                                                     |                                                                                                                                                                |
| `items[].createdAt`      | date-time                                                                                                   |                                                                                                                                                                |
| `currency`               | string                                                                                                      |                                                                                                                                                                |
| `mrr`                    | money or null                                                                                               | The items' monthly recurring amount (licensed items, before discounts and tax).                                                                                |
| `collectionMethod`       | one of `charge_automatically`, `send_invoice`                                                               |                                                                                                                                                                |
| `daysUntilDue`           | integer or null                                                                                             |                                                                                                                                                                |
| `defaultPaymentMethodId` | `pm_…` ID or null                                                                                           |                                                                                                                                                                |
| `billingCycleAnchor`     | date-time                                                                                                   |                                                                                                                                                                |
| `currentPeriodStart`     | date-time                                                                                                   |                                                                                                                                                                |
| `currentPeriodEnd`       | date-time                                                                                                   |                                                                                                                                                                |
| `trialStart`             | date-time or null                                                                                           |                                                                                                                                                                |
| `trialEnd`               | date-time or null                                                                                           |                                                                                                                                                                |
| `trialEndBehavior`       | one of `convert`, `cancel_if_no_payment_method`, `pause_if_no_payment_method`                               |                                                                                                                                                                |
| `cancelAtPeriodEnd`      | boolean                                                                                                     |                                                                                                                                                                |
| `cancelAt`               | date-time or null                                                                                           |                                                                                                                                                                |
| `canceledAt`             | date-time or null                                                                                           |                                                                                                                                                                |
| `endedAt`                | date-time or null                                                                                           |                                                                                                                                                                |
| `cancellation`           | object or null                                                                                              |                                                                                                                                                                |
| `pause`                  | object or null                                                                                              |                                                                                                                                                                |
| `discountIds`            | array of `disc_…` ID                                                                                        |                                                                                                                                                                |
| `pendingUpdate`          | object or null                                                                                              |                                                                                                                                                                |
| `latestInvoiceId`        | `inv_…` ID or null                                                                                          |                                                                                                                                                                |
| `incompleteExpiresAt`    | date-time or null                                                                                           |                                                                                                                                                                |
| `testClockId`            | `clk_…` ID or null                                                                                          |                                                                                                                                                                |
| `dunning`                | object or null                                                                                              | Dunning (§16.10) while past due or unpaid; null otherwise.                                                                                                     |
| `usageThreshold`         | money or null                                                                                               | Unbilled metered usage worth this much is invoiced at once (spec §16.7).                                                                                       |
| `entitlementGraceUntil`  | date-time or null                                                                                           |                                                                                                                                                                |
| `metadata`               | object                                                                                                      |                                                                                                                                                                |
| `version`                | integer                                                                                                     |                                                                                                                                                                |
| `createdAt`              | date-time                                                                                                   |                                                                                                                                                                |
| `updatedAt`              | date-time                                                                                                   |                                                                                                                                                                |

## Examples

### An active subscription

```http
GET /api/v1/subscriptions/sub_01m4tx5nj8emwbyf7y9vcf47z5
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "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"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                             | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No subscription with this ID is visible to the request.          | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`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): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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), [`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).