Upgrade a customer's subscription to a different plan with automatic proration. This is a protected endpoint which requires proper authorization header to authenticate the customer.
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 |
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
- Create Subscription - Create a new subscription
- Cancel Subscription - Cancel an existing subscription
- Reactivate Subscription - Reactivate a canceled subscription
- Renew Subscription - Renew an expired subscription