Pause a subscription · Ownrecord docs

Pauses an active subscription: collection stops until it resumes, at resumesAt or with subscriptions.resume. behavior says what happens to the invoices of the periods that pass meanwhile: void (none are created; the default), keep_as_draft (created, not finalized) or mark_uncollectible (created and written off). The customer's entitlements stop during the pause (the brand default), and the subscription stops counting for MRR. Emits subscription.paused.

At a glance

REST: POST /api/v1/subscriptions/{id}/pause
MCP tool: subscriptions_pause
Operation ID: subscriptions.pause
Scope: Brand
Permission: subscriptions:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the subscriptions:write scope
Since: M5

Request

Path parameters

Field	Type	Description
`id`	`sub_…` ID

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`expectedVersion`	integer (at least 1)	No
`behavior`	one of `keep_as_draft`, `void`, `mark_uncollectible`	No	What happens to the invoices while paused: `keep_as_draft` (created, not finalized), `void` (none) or `mark_uncollectible` (created and written off).
`resumesAt`	date-time	No	Resume automatically at this time.

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

Pause for a month

HTTP

POST /api/v1/subscriptions/sub_01m4tx5nj8emwbyf7y9vcf47z5/pause
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "behavior": "void",
  "resumesAt": "2026-11-20T09:00:00.000Z"
}

Response (200):

JSON

{
  "id": "sub_01m4tx5nj8emwbyf7y9vcf47z5",
  "object": "subscription",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47zm",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47z4",
  "status": "paused",
  "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": {
    "behavior": "void",
    "resumesAt": "2026-11-20T09:00:00.000Z",
    "pausedAt": "2026-10-20T09:00:00.000Z"
  },
  "discountIds": [],
  "pendingUpdate": null,
  "latestInvoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47zn",
  "incompleteExpiresAt": null,
  "testClockId": null,
  "dunning": null,
  "usageThreshold": null,
  "entitlementGraceUntil": null,
  "metadata": {
    "crm_account": "A-1042"
  },
  "version": 3,
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-20T09:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is malformed or out of range.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	No subscription (or customer, price, coupon) 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.
`version_conflict`	409	The subscription changed since you read it (`expectedVersion`), or at the same time; read it and retry.	Fetch the object again and retry the change.
`subscription_status_invalid`	409	The subscription's status doesn't allow this (spec §16.1): see `details.reason`.	Check `details.status`: items change only while trialing, active or past due; pausing needs an active subscription and resuming a paused one; reactivating needs a cancellation scheduled for the period end; canceled and expired subscriptions don't change.
`permission_denied`	403	The credentials can't change this brand's subscriptions (`subscriptions:write`).	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, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Pause for a month#

Errors#