Change plan or quantity of a subscription

Changes a subscription's items, quantities, discount, payment method, collection method or metadata.

Items (items[]): { id, priceId } swaps the price of an item, { id, quantity } changes its seats, { priceId, quantity } adds an item and { id, deleted: true } removes one; items not named stay. When the change applies (effective) and how it is billed (prorationBehavior) follow spec §16.5:

Upgrades (a higher monthly amount) and interval changes default to now with always_invoice: the unused time of the old items is credited, the remaining time of the new ones charged, and the difference invoiced and charged at once (an interval change starts a new billing period now). If the payment fails, the change stays and the open invoice goes to dunning, unless paymentBehavior: pending_if_incomplete keeps the old items until the invoice is paid.
Downgrades and lateral changes default to the end of the period: the change is stored as pendingUpdate and applied at renewal, with no credit.
now with create_prorations: a net charge waits for the next invoice as pending invoice items; a net credit (fewer seats) goes to the customer's credit balance at once.
none: the items change now and nothing is billed.

Trialing subscriptions change at once with nothing to bill. Proration is exact to the second, rounded once per line; proration lines are taxed at the rates of the change date. Preview a change first with subscriptions.preview_change (the exact invoice), or dry-run this operation. Emits subscription.updated.

At a glance

REST: PATCH /api/v1/subscriptions/{id}
MCP tool: subscriptions_update
Operation ID: subscriptions.update
Scope: Brand
Permission: subscriptions:write
Risk tier: financial
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
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	The `version` you read (optimistic concurrency).
`items`	array of object	No	Item changes: `{ id, priceId }` swaps a price, `{ id, quantity }` changes seats, `{ priceId, quantity }` adds an item, `{ id, deleted: true }` removes one. Items not named stay.
`items[].id`	`si_…` ID	No	The item to change or remove (`si_…`); leave out to add one.
`items[].priceId`	`price_…` ID	No	The new price of the item, or of a new item.
`items[].quantity`	integer (1 to 1000000)	No	Seats or units of a licensed price (1 to 1,000,000). Metered prices take no quantity.
`items[].deleted`	boolean	No	Remove the item (with `id`).
`prorationBehavior`	one of `create_prorations`, `always_invoice`, `none`	No	`create_prorations` (credit unused time and charge the remaining time on the next invoice; a net credit goes to the customer credit balance), `always_invoice` (invoice the proration now) or `none`.
`effective`	one of `now`, `period_end`	No	`now`, or at the end of the current period (`period_end`, stored as `pendingUpdate`). Default: upgrades and interval changes now with `always_invoice`, downgrades at the period end.
`paymentBehavior`	one of `allow_incomplete`, `pending_if_incomplete`	No	For a change invoiced now: `allow_incomplete` (default; the change applies and a failed payment goes to dunning) or `pending_if_incomplete` (the old items stay until the invoice is paid).
`couponId`	`cpn_…` ID	No	Apply a coupon to the subscription.
`promotionCode`	string	No	A promotion code as the customer typed it (case doesn't matter).
`collectionMethod`	one of `charge_automatically`, `send_invoice`	No	`charge_automatically` (the default payment method is charged) or `send_invoice` (the invoice is emailed with bank transfer details and paid by the due date).
`daysUntilDue`	integer (0 to 365) or null	No
`defaultPaymentMethodId`	`pm_…` ID or null	No	The payment method charged for this subscription (`null`: the customer's default).
`cancelPendingUpdate`	boolean	No	Drop a change scheduled for the period end (`pendingUpdate`).
`usageThreshold`	object or null	No	Invoice metered usage as soon as what it would charge reaches this amount (spec §16.7): limits the credit risk of usage-heavy customers. In the subscription's currency, whole minor units. `null` removes it.
`metadata`	object	No	Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.

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

Upgrade to Pro now

The unused Basic time is credited and the Pro time to the period end is invoiced and charged now.

HTTP

PATCH /api/v1/subscriptions/sub_01m4tx5nj8emwbyf7y9vcf47z5
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "items": [
    {
      "id": "si_01m4tx5nj8emwbyf7y9vcf47za",
      "priceId": "price_01m4tx5nj8emwbyf7y9vcf47y3"
    }
  ],
  "expectedVersion": 2
}

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_01m4tx5nj8emwbyf7y9vcf47y3",
      "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
      "quantity": 3,
      "createdAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "currency": "EUR",
  "mrr": {
    "amount": "147000000",
    "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": 3,
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-20T09:00:00.000Z"
}

Two seats fewer from the next period

HTTP

PATCH /api/v1/subscriptions/sub_01m4tx5nj8emwbyf7y9vcf47z5
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "items": [
    {
      "id": "si_01m4tx5nj8emwbyf7y9vcf47za",
      "quantity": 1
    }
  ],
  "effective": "period_end"
}

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": {
    "kind": "period_end",
    "items": [
      {
        "id": "si_01m4tx5nj8emwbyf7y9vcf47za",
        "priceId": "price_01m4tx5nj8emwbyf7y9vcf47y2",
        "productId": "prod_01m4tx5nj8emwbyf7y9vcf47y0",
        "quantity": 1,
        "createdAt": "2026-10-13T12:00:00.000Z"
      }
    ],
    "effectiveAt": "2026-11-13T12:00:00.000Z",
    "requestedAt": "2026-10-20T09:00:00.000Z",
    "prorationBehavior": "none",
    "invoiceId": null,
    "expiresAt": 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.
`subscription_item_not_found`	404	An item `id` isn't one of the subscription's items.	Read the subscription and use one of its `items[].id` (`si_…`); to add a new price, leave out `id`.
`subscription_price_invalid`	400	A new price isn't recurring, is archived, is in another currency, or its interval doesn't combine.	Use active recurring prices of one currency whose intervals are whole multiples of each other (monthly with yearly, weekly with 2-weekly). `details.reason` says what's wrong and `param` names the item.
`subscription_meter_conflict`	409	Another live item of the customer already bills this meter.	Change the existing subscription's metered item instead, or cancel it first. A customer has at most one active metered item per meter.
`subscription_change_invalid`	400	A change waits for its invoice to be paid, or `pending_if_incomplete` was asked for a `send_invoice` subscription.	Check `details.reason` and adjust the request.
`subscription_payment_method_invalid`	400	`defaultPaymentMethodId` isn't a saved, attached payment method of the customer.	Use a saved payment method (`pm_…`) of the subscription's customer that isn't detached, or leave it out to use the customer's default.
`coupon_not_redeemable`	409	The coupon is archived, expired or used up.	Check `details.reason`: reactivate an archived coupon, or create a new coupon when it expired or reached its redemption limit.
`promotion_code_not_redeemable`	409	The promotion code can't be used (`details.reason`).	Check `details.reason` and tell the customer: the code may have expired, be used up, belong to another customer, need a larger purchase or be for first-time customers only.
`discount_already_applied`	409	The coupon is already applied to this subscription.	End the existing discount first (`discounts.delete`), or apply a different coupon. The same coupon doesn't stack with itself.
`registration_required`	422	An invoice issued now can't be taxed: the seller isn't registered where the customer is (a new sale).	Register the entity for the regime named in `details.regime` (see its prerequisites and deadline), or arm the jurisdiction once the prerequisites are done. The customer can join the waitlist meanwhile.
`jurisdiction_blocked`	422	The customer's location is blocked for new sales.	This jurisdiction isn't covered by usable tax knowledge for this seller. Contact support if you need to sell there.
`evidence_conflict`	422	The customer's stored location evidence isn't enough to tax an invoice issued now (§13.3).	Collect another piece of location evidence (billing address, card country, or the customer's confirmation of their country) and quote again.
`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_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#

Upgrade to Pro now#

Two seats fewer from the next period#

Errors#