--- title: "How subscription plan changes work" source: https://support.storeconnect.com/articles/subscription-plan-changes type: article format: markdown site: StoreConnect Support — product and developer documentation for StoreConnect site_index: https://storeconnect.com/llms.txt docs_index: https://support.storeconnect.com/llms.txt note: Append .md to any page or article URL on this site to get its Markdown form. --- # 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](storeconnect-api) article covers the request, the response, and the error reasons. [API configuration](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](#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](#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](#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](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](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](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. --- ## Follow StoreConnect - [Email Newsletter](https://storeconnect.com/c/lp-newsletter) - [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464) - [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g) - [LinkedIn](https://www.linkedin.com/company/storeconnect) - [X / Twitter](https://x.com/storeconnecthq) ## Popular Links - [Partners](https://storeconnect.com/partners) - [Become a Partner](https://storeconnect.com/become-a-partner) - [News](https://storeconnect.com/articles/news) - [Events](https://storeconnect.com/articles/events) - [Feature Comparison](https://storeconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://storeconnect.com/contact) ## Documentation - [Help documentation](https://support.storeconnect.com/help-documentation) - [AI agents](https://support.storeconnect.com/ai) - [Videos & tutorials](https://support.storeconnect.com/videos-tutorials) - [Developer reference](https://support.storeconnect.com/developer-reference) - [Release notes](https://support.storeconnect.com/release-notes) - [Troubleshooting](https://support.storeconnect.com/troubleshooting) - [Trust Center](https://trust.getstoreconnect.com/) - [Status Page](https://status.storeconnect.com/) ## Contact - info@getstoreconnect.com - US +1 415 745 3230 - AUS +61 2 8365 2308 100 S Ashley Dr, Suite 600-2461 Tampa FL 33602-600 USA Level 22, Sydney Place 180 George Street Sydney, NSW, 2000, AUS ## Machine-readable - [Site index for agents](https://storeconnect.com/llms.txt): curated map of the StoreConnect site in llms.txt format - [Documentation index for agents](https://support.storeconnect.com/llms.txt): full technical and product documentation map Every page and article on this site has a Markdown rendering: append `.md` to its URL. Continue in Markdown: [Help documentation](https://support.storeconnect.com/help-documentation.md) · [Developer reference](https://support.storeconnect.com/developer-reference.md) · [Videos & tutorials](https://support.storeconnect.com/videos-tutorials.md) · [Release notes](https://support.storeconnect.com/release-notes.md) --- StoreConnect Support — https://support.storeconnect.com/articles/subscription-plan-changes