How subscription plan changes work

This topic is relevant if you sell subscriptions and need to know what happens when a customer moves between plans, or how to configure the proration that applies.

A plan change moves an active subscription from one subscription product to another, for example from a Silver plan to a Gold plan. StoreConnect decides whether the change is an upgrade or a downgrade purely by comparing the two recurring prices.

• Upgrade: the new plan costs more.
• Downgrade: the new plan costs less.

The comparison uses each plan’s price for one term, not a monthly or yearly equivalent. Moving from a $240 annual plan to a $25 monthly plan is a downgrade, even though the monthly plan costs more over a year.

How a plan change is made

Plan changes are made through the StoreConnect API only. Your developer or integration sends a PATCH /subscriptions/{id} request with the ID of the new plan’s product:

```json

{ “product_id”: “01tQE00000ABcdEYAT” } ```

product_id accepts the new product’s Salesforce ID, slug, or product code. The subscription returned by the API shows the product’s Salesforce ID.

The request includes only the new product. StoreConnect works out the direction, timing, and any charge from the price difference.

The StoreConnect API article covers the request, the response, and the error reasons. API configuration covers the setup a store needs before it can accept API calls.

There is no other way to make a plan change:

• The storefront has no button or account page where a customer can change their own plan.
• Salesforce has no plan change action. Editing the Product or Term Price directly on a Subscription record is not a plan change: no proration is charged and no Subscription Change record is written.

Which subscriptions can change plans

A plan change is accepted only when all of these are true. Otherwise the API rejects it and nothing changes.

• The subscription is evergreen (ongoing and auto-renewing). Fixed-term subscriptions cannot change plans.
• The subscription status is active.
• The new plan has a price in the store’s price book, and that price differs from the subscription’s current Term Price. A change to a different plan at the same price is rejected.
• For an upgrade that is charged at the time of the change, the subscription has a saved payment method. See The plan change charge.

A request naming the plan the subscription is already on is not a plan change. It cancels a scheduled downgrade instead. See Cancel a scheduled downgrade.

What happens on an upgrade and a downgrade

	Upgrade	Downgrade
When the new plan takes effect	Immediately	At the next renewal
Customer charged at the time of the change	Depends on the proration mode (see Proration). With Prorate Immediately, the customer pays a prorated amount for the rest of the current period. With No Proration, the customer pays nothing now.	No
Credit or refund issued	No	No
What the customer has until renewal	The new, higher plan straight away	The current, higher plan
Recurring price from the next renewal	The new, higher price	The new, lower price

A downgrade lets the customer keep what they have already paid for until the period ends.

Proration

Proration is how StoreConnect handles the price gap when a customer upgrades partway through a billing period they have already paid for at the lower price.

The proration mode applies to upgrades only. A downgrade is never charged at the time of the change. StoreConnect schedules the downgrade for the next renewal, whatever the mode.

Mode	Stored value	On an upgrade
Prorate Immediately	prorate_immediately	The customer is charged a prorated top-up covering the days left in the current period, and the higher plan applies right away. This is the default.
Prorate on Renewal	prorate_on_renewal	Not supported. The upgrade is rejected.
No Proration	no_proration	The higher plan applies right away and the customer is charged nothing now. The full new price starts at the next renewal.

The prorated amount is the daily price difference multiplied by the days left until the Next Billing Date. For example, a customer on a $30 monthly Silver plan who upgrades to a $60 Gold plan with 15 days left in a 30-day period is charged $15.00: ($60 − $30) ÷ 30 days × 15 days.

If a customer changes plans more than once in the same period, StoreConnect deducts the amounts already charged for earlier upgrades in that period. The customer is not charged twice for the same days.

How the proration mode is chosen

StoreConnect checks these settings in order and uses the first one that is set:

1. Plan Change Mode on the new plan’s subscription product (s_c__Subscription_Plan_Change_Mode__c), set to Prorate Immediately, Prorate on Renewal, or No Proration.
2. The subscriptions.plan_change_mode store variable, which sets a default for the whole store. It takes the stored values prorate_immediately, prorate_on_renewal, or no_proration. See Store variables.
3. prorate_immediately, the built-in default.

Because Prorate on Renewal rejects upgrades, setting it on a product means customers can only downgrade to that product, not upgrade to it.

The plan change charge

StoreConnect charges the customer only for an upgrade under Prorate Immediately where the prorated amount is above zero. Downgrades, No Proration upgrades, and rejected Prorate on Renewal upgrades create no charge. When StoreConnect does charge for a plan change:

• The subscription’s saved payment method is charged. The change is rejected if the subscription has no saved payment method.
• The charge is a one-off. It does not move the Next Billing Date, so the next renewal still falls on its normal date.
• The Payment has an Origin of SP01, so a Flow can tell a plan change charge apart from a renewal charge (SU01). See Payment origin codes.
• If the charge fails, the whole plan change is rolled back and nothing is applied. The subscription is not marked delinquent, because delinquency is reserved for failed renewal charges. See Manage delinquent subscription payments.

Tax on the plan change charge

StoreConnect adds tax to the plan change charge. The tax is worked out on the prorated amount. StoreConnect uses the taxes on the new plan’s product, whether assigned directly or through a tax group.

Whether tax is added on top depends on the new product’s price:

• Tax-exclusive pricing: the tax is added on top of the prorated amount.
• Tax-inclusive pricing: the tax is already part of the prorated amount, so the charge does not change.

No StoreConnect tax is charged in two cases:

• The customer’s account is tax-exempt.
• The store uses an external tax provider, such as Avalara. Plan change orders on these stores carry no tax at all.

No refund on a downgrade

When a customer moves to a cheaper plan, StoreConnect does not refund the price difference and does not add store credit for the unused part of the higher plan. The customer keeps the higher plan until the period ends, then pays the lower price from the next renewal onward.

The Account Credit system is not connected to plan changes. A plan change never creates account credit, and account credit is never used to offset one.

Cancel a scheduled downgrade

A downgrade does not apply until the next renewal, so you can cancel it before then. To cancel a scheduled downgrade, send a PATCH /subscriptions/{id} request with the product the subscription is on now. In this example, 01tQE00000XYzaBYAT is the current plan’s product:

```json

{ “product_id”: “01tQE00000XYzaBYAT” } ```

The subscription stays on the current plan and renews at the current price. No order or payment is created.

You can cancel a scheduled downgrade whatever the subscription status. That way, the downgrade does not apply if a suspended or expired subscription resumes. When no downgrade is scheduled, the API rejects the request with the reason no_pending_plan_change.

Upgrading again before the renewal also cancels a scheduled downgrade.

What is recorded in Salesforce

Every plan change writes a Subscription Change record (s_c__Subscription_Change__c), which is the audit trail for the subscription.

Every plan change also generates an Order: a charge order for a prorated upgrade, or a zero-value order otherwise. StoreConnect finalizes and completes the order the same way as a renewal order, so order completion automation, confirmation emails, and Retail Express sync all run for it.

Field	API name	What it holds
Direction	s_c__Direction__c	initial, upgrade, downgrade, or cancellation
Plan Change Mode	s_c__Plan_Change_Mode__c	The mode applied to this change
Old Price	s_c__Old_Price__c	The recurring price before the change
New Price	s_c__New_Price__c	The recurring price after the change
Old Product	s_c__Old_Product_Id__c	The plan before the change
New Product	s_c__New_Product_Id__c	The plan after the change
Proration Amount	s_c__Proration_Amount__c	The prorated amount charged, 0 for downgrades and No Proration changes
Effective Date	s_c__Effective_Date__c	Now for an upgrade, the next billing date for a downgrade
Order	s_c__Order_Id__c	The order generated for this change

A Subscription Change with a direction of initial and a proration amount of 0 is also written when a subscription is first created, so the history is complete from signup. Canceling a scheduled downgrade writes one with a direction of cancellation and no order, so the history shows the downgrade was scheduled and then withdrawn.

On the subscription itself, Product (s_c__Product_Id__c), Term Price (s_c__Period_Price__c), and the billing term update immediately on an upgrade, and at renewal for a downgrade.

To see whether a downgrade is scheduled, check the Subscription Changes related list on the subscription. Through the API, a scheduled downgrade appears as pending_plan_change on the subscription.

Behavior notes

• StoreConnect applies a downgrade at renewal before taking the renewal charge, so the renewal always bills the new, lower price.
• The subscription takes on the new plan’s billing term as well as the new plan’s price. A customer who downgrades from an annual plan to a monthly plan renews monthly from the annual renewal date.
• If the new plan’s product grants a membership, an upgrade assigns that membership to the customer’s account straight away.