Get a subscription · Ownrecord docs

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`	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`	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: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, scope_required, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

An active subscription#

Errors#