API ReferenceSubscriptions

Change Plan

View as Markdown
Change subscription plan with term-aware splitting. Performs an atomic operation when items change billing intervals or contract terms. Items are grouped by target SubscriptionTerms and new subscriptions are created for each different combination of interval + contract terms. **Actions:** Each item specifies an explicit action: - **ADD**: Create a new item (requires new_price_id, forbids subscription_item_id) - **UPDATE**: Update existing item (requires subscription_item_id and new_price_id) - **DELETE**: Remove existing item (requires subscription_item_id, forbids new_price_id) **Key Behaviors:** - **Partial mapping**: Only items in the request are changed; others stay unchanged - **Same terms → stays**: Items mapping to same interval+contract stay on original - **Different terms → moves**: Items grouped by terms, 1 new sub per unique terms - **Contract-aware**: Same interval + different contract = separate subscriptions **Examples:** 1. Add new item + update existing: ```json {"items": [ {"action": "add", "new_price_id": "prc_xxx", "quantity": 1}, {"action": "update", "subscription_item_id": "si_yyy", "new_price_id": "prc_zzz"} ]} ``` 2. Mixed actions with term change: ```json {"items": [ {"action": "delete", "subscription_item_id": "si_old"}, {"action": "add", "new_price_id": "prc_annual", "quantity": 2} ]} ``` **Proration:** - Credit for unused time on moved/deleted items (negative) - Charge for full new period on new subscriptions (positive) - New periods start from NOW (fresh start model) **Lineage Tracking:** - New subscriptions include `split_from_subscription` in the response Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

subscription_idstringRequired
account_idstringRequired

Request

This endpoint expects an object.
itemslist of objectsRequired
Mappings for items that are changing
proration_behaviorenumRequired
How to handle proration for the change. Callers must explicitly choose a behavior.
reasonstringOptionalDefaults to change_plan
Reason for the plan change
trial_behaviorenumOptional

What to do with an in-progress trial. ‘preserve’ (default) keeps the original trial end date: the plan changes immediately but nothing is billed until the trial ends, at which point the first real period is charged at the new price. ‘end_now’ ends the trial immediately and bills straight away. Either way the change is applied in place — the subscription is not replaced and no proration or credit is produced for trial time, which was never paid for. Ignored unless the subscription is currently in a trial that has not yet ended.

pay_before_changebooleanOptionalDefaults to true

Whether payment must succeed before the plan change takes effect. If true, the original subscription remains unchanged until the proration invoice is paid. New subscriptions are created in ‘incomplete’ state, and the original subscription’s items are NOT deactivated and the original is NOT cancelled until payment succeeds. Returns HTTP 402 with the invoice to collect. If payment fails, customer stays on their original subscription with no disruption. If false, the plan change commits immediately regardless of payment status, and new subscriptions may be left in ‘incomplete’ state if payment fails. Requires proration_behavior=always_invoice when true.

effective_atenumOptional

When the plan change should take effect. ‘immediate’ executes the change now. ‘period_end’ schedules the change to execute at the end of the current billing period.

metadatamap from strings to any or nullOptional

Additional metadata to add to new subscription(s)

Response

Successful Response
original_subscription_idstring
ID of the original subscription
original_cancelledboolean

True if original was cancelled (all items moved/deleted)

original_items_remaininginteger
Number of active items still on original subscription
original_subscription_updated_atdatetime
Last update timestamp of the original subscription
created_subscriptionslist of objectsOptional

New subscriptions created (one per SubscriptionTerms)

items_addedintegerOptionalDefaults to 0
Number of new items created via ADD action
proration_credit_atomintegerOptionalDefaults to 0

Credit for unused time on moved/deleted items (negative)

proration_charge_atomintegerOptionalDefaults to 0

Charge for new subscription periods (positive)

net_amount_atomintegerOptionalDefaults to 0

Net proration amount (credit + charge)

invoice_idstring or nullOptional

ID of proration invoice (if always_invoice)

payment_statusstring or nullOptional

Payment status (paid, failed, no_payment_method)

voided_invoice_idslist of stringsOptional
IDs of voided pending renewal invoices
effective_atstring or nullOptional

‘period_end’ if change is deferred, None if immediate

scheduled_fordatetime or nullOptional

When the deferred change will execute (period_end datetime)

pending_change_idstring or nullOptional

ID of the pending change (for cancellation/lookup)

Errors

409
Conflict Error
422
Unprocessable Entity Error