Overview

Use this endpoint to change a customer's subscription from one plan to another. This is commonly called an "upgrade" since the API only allows changing to higher-priced plans.

When a subscription is changed:

The system calculates the proration (credit for unused time on the old plan)
A new invoice is generated for the price difference
The customer is charged immediately for the prorated amount
The subscription continues with the new plan

Request Body

Parameter	Type	Required	Description
`subscription_id`	integer	Yes	The ID of the subscription to change
`plan_id`	integer	Yes	The ID of the new plan to switch to
`address_id`	integer	No	The ID of the address that will be associated with the new plan (Available only if taxes are disabled)

Example request:

{
  "subscription_id": 12345,
  "plan_id": 678
}

Restrictions

The subscription change endpoint enforces several business rules to ensure billing integrity. Understanding these restrictions helps you build better user experiences.

Plan Restrictions

Restriction	Error Message	Why
Cannot downgrade	"Sorry, you cannot switch to a lower-priced plan."	Downgrades could create negative invoices due to proration calculations. Only upgrades to higher-priced plans are allowed.
Same plan type required	"Sorry, you cannot switch to a plan with different type."	You cannot switch between `regular` and `membership` plan types. The billing logic differs between these types.
No archived plans	"Cannot change subscription to an archived plan."	Archived plans are retired and no longer available for new subscriptions or changes.
No trial plans	"Cannot change subscription to a trial plan."	Plans with trial periods cannot be used as upgrade targets.
Same currency required	"Sorry, you cannot switch to a plan with a different currency."	Multi-currency changes are not supported. The new plan must use the same currency as the current plan.
No group user plans	"Cannot change to a group user plan."	Plans that are part of a group subscription (with a `parent_plan_id`) cannot be selected as upgrade targets.

Subscription State Restrictions

Restriction	Error Message	Why
Cannot be expired/canceled	"Subscription cannot be updated because it has already expired."	Only active subscriptions can be changed. Expired or canceled subscriptions must be renewed first.
Cannot be incomplete	"Subscription cannot be updated because it is incomplete."	Subscriptions with pending payment setup cannot be modified until payment is confirmed.
Cannot be redeemed gift	"Subscription cannot be updated because it has already been redeemed."	Gift subscriptions that have been redeemed by a recipient cannot be upgraded by the original purchaser.
Cannot have multiple items	"Subscription cannot be updated because it contains multiple items."	Multi-item subscriptions require special handling and cannot use the standard change flow.

Advanced Restrictions

Restriction	Error Message	Why
No shipment-based plans	"Cannot change subscription from/to a plan that includes shipments."	Subscriptions with physical shipments have different fulfillment logic and cannot be changed through this endpoint.
No switching between time/shipment-based	"Sorry, you cannot switch between shipment-based and time-based plans."	These plan types have fundamentally different billing and fulfillment cycles.
Cannot have future phases	"Subscription cannot be updated because it has future phases."	Subscriptions with scheduled future changes must have those phases canceled before making immediate changes.
Coupon must be valid on new plan	"Subscription cannot be updated because it is tied to a coupon that is not available on the new plan."	If the subscription has an active coupon, that coupon must also be valid for the target plan.
Once-only coupon restriction	"Subscription cannot change plans because it has invoices with once-only coupons applied."	Subscriptions that have used a one-time coupon cannot be changed to prevent coupon abuse.
Customer segment must match	"Sorry, you cannot switch to this plan, due to user segment mismatch."	If the target plan has customer segment restrictions, the customer must belong to an eligible segment.

Proration Behavior

When a subscription is changed, the system automatically handles proration:

Credit calculation: The unused portion of the current billing period is calculated and credited
New charges: The prorated amount for the new plan is calculated for the remaining period
Invoice generation: A new invoice is created for the difference
Immediate charge: The customer is charged immediately

Example scenario:

Customer is on a $10/month plan, 15 days into the billing period
Customer upgrades to a $20/month plan
Credit for unused time: ~$5 (15 days remaining)
Charge for new plan: ~$10 (15 days at $20/month rate)
Net charge: ~$5

Best Practices

Check eligibility first: Before showing upgrade options to customers, verify the target plans meet all restrictions (same type, same currency, higher price, not archived).
Handle coupon scenarios: If a subscription has a coupon, only show plans where that coupon is also valid.
Explain proration: Show customers the prorated amount they'll be charged before confirming the upgrade.
Handle scheduled changes: If a subscription has future phases, prompt the customer to cancel them before upgrading.
Segment-aware UI: If using customer segments, only display plans available to the customer's segment.

Related Endpoints