About Subscription Plan Changes and Billing Proration

Shopify App Store
1

Hello!

Currently, our app has only one subscription plan, which is an annual plan. We are planning to introduce a total of new 12 plans: 6 annual plans and 6 monthly plans. We would like to understand how Shopify App Credits handle subscription changes on subscription plan change. Specifically, when a merchant upgrades to a higher-priced plan or downgrades to a lower-priced plan, how does Shopify manage the billing and credits? For example: If a store is currently on our existing annual plan and upgrades to a new annual plan with a higher price, will Shopify automatically handle the proration according to its billing cycle? Let’s say the merchant has already paid 1000 for the current annual plan and then upgrades to a new annual plan priced at around 2000+. Will Shopify charge only the remaining difference based on usage, and if so, how soon is this charge issued (immediately or within a certain number of days)?

Additionally, we would appreciate guidance on how to correctly handle the following transitions: Switching from an annual plan to a monthly plan: should this be handled using APPLY_ON_NEXT_BILLING_CYCLE or as a STANDARD? Switching from a monthly plan to an annual plan: should this be handled using APPLY_ON_NEXT_BILLING_CYCLE or as a STANDARD change? Thanks in advance for your help.

EDIT(more questions):

:one: Annual → Annual downgrade (price decrease)

Example:
A merchant purchases a $1,000 annual plan and downgrades to a $600 annual plan shortly after (e.g., the next day).

Questions:

  1. Does Shopify automatically calculate unused time and apply it as app credits in this scenario?

  2. Are app credits guaranteed to be applied, or is this behavior discretionary?

  3. is credit mechanism will work here?

  4. Can Shopify adjust the charge so that the merchant is effectively charged only the net amount (e.g., $200 instead of $600), or will the full $600 always be charged?

:two: Annual → Annual upgrade (price increase)

Example:
A merchant pays $1,000 for an annual plan and upgrades to a $2,000+ annual plan.

Questions:

  1. Is the upgrade charge issued immediately, or at the next billing anchor?

  2. Does Shopify prorate the unused portion of the previous plan and apply it as app credit?

  3. Is Shopify guaranteed to charge only the difference, or can the full new plan amount be charged regardless of unused time?

:three: Annual → Monthly plan change

Example:
A merchant switches from a $1,000 annual plan to a $350 monthly plan.

Questions:

  1. Does Shopify convert the remaining annual prepaid time into monthly coverage?

  2. Will the merchant be charged again after a certain number of months (e.g., after 3 months)?

  3. Is there any recommended or required replacementBehavior for this transition (STANDARD vs APPLY_ON_NEXT_BILLING_CYCLE)?

:four: Monthly → Annual plan change

Questions:

  1. Does Shopify apply unused monthly time as app credit when switching to an annual plan?

  2. Is there any recommended or required replacementBehavior for this transition?

:five: App credits behavior (general)

Questions:

  1. Are app credits automatically applied to the next subscription charge, or only to future cycles?

  2. Can app credits expire or fail to apply under certain conditions?

  3. Is there any way for apps to predict or rely on app credit application behavior?

:six: Best practices confirmation

Question:
From Shopify’s perspective, is it considered best practice to:

  • Apply downgrades and billing interval changes at the end of the current billing cycle, and

  • Apply upgrades immediately?

1 Like
3

Hey @Mehmet_Talha_Seker,

Great questions. I’ll start by generally clarifying the expected billing behavior:

When you create a new subscription for a merchant with an existing one, this either applies immediately or defers it to the next billing cycle. The replacementBehavior parameter controls this.

With STANDARD (default), changes are deferred for:

  • Annual → Annual downgrade (same currency, lower price)

  • Annual → Monthly (same currency)

  • Same plan with different discount

Everything else applies immediately with proration.

When deferred, the merchant continues on their current plan until it expires. No credits are issued as there’s nothing to prorate since they use the full cycle they paid for. Credits only apply when using APPLY_IMMEDIATELY.

One other note: app credits go to the merchant’s overall Shopify invoice, not tied to your specific app. Credits from any app can offset charges from any other app. They should not be used to offer credit to be used within your own app.

Now, Your Scenarios

1. Annual → Annual downgrade: Deferred. No credits. New plan starts when current period ends.

2. Annual → Annual upgrade: Immediate with prorated charge for the difference.

3. Annual → Monthly: Deferred. No credits. Monthly billing starts after annual period ends.

4. Monthly → Annual: Immediate with proration.

5. App credits: Applied to merchant’s next Shopify invoice (any app).

6. Best practice: STANDARD works well. It protects annual subscribers on downgrades while applying upgrades immediately.

4

Hey @KyleG-Shopify, thanks a lot for the response!

So, as I understand it, using Standard should be sufficient for all scenarios. However, I’m a bit concerned about this case:

3. Annual → Monthly: Deferred. No credits. Monthly billing starts after annual period ends.

Here’s what’s confusing to me:
Let’s say a merchant is on a $1000 annual Standard plan and after 2 months they switch to a $350 monthly Plus plan.
With the deferred behavior, they would continue on the annual plan until the end of the year, meaning they’d effectively be using the monthly Plus plan features for 10 more months while only having paid for the annual Standard plan.

This feels like an outcome we wouldn’t want. Am I understanding this correctly, or is there something I’m missing in how this scenario is handled?

5

Hey @Mehmet_Talha_Seker, in this scenario, you should only give the merchant the monthly plan features once the year ends. If you want the merchant to have the monthly plan features immediately you should use the APPLY_IMMEDIATELY replacement behaviour on the mutation.

Keep in mind that when you use apply immediately for a change from annual to monthly it could result in a revenue deduction for the credits that would be applied.

6

Hi @KyleG-Shopify ,

just to clarify: We don’t have replacementBehaviour set (which means it’s STANDARD by default I assume?)

In the following scenario:

  1. merchant purchases yearly subscription
  2. merchant upgrades to higher Yearly subscription midway through their year
  3. then immediately downgrades again to lower Yearly subscription on the same day

See this screenshot:

image
image580×904 90.7 KB

How does the billing work in this scneario? Can you walk me through it in detail?

In particular, do we receive the payout for the upgrade, even though they downgraded again on the same day?

7

Hey @Felix_Wu,

Yes, you should receive the payout for the upgrade. With STANDARD behavior, the upgrade applies immediately with proration, but the downgrade is deferred to the next billing cycle per STANDARD rule #1 (annual→annual downgrade = deferred).

What happens:

Same day (midway through annual cycle):
├─ Upgrade to €335.76/year → Applies immediately with prorated charge
├─ Merchant now on higher plan (€335.76/year)
├─ Downgrade to €178.88/year → Deferred to next billing cycle
└─ Merchant stays on €335.76/year plan until renewal

Next billing cycle (renewal date):
└─ Downgrade activates → Merchant moves to €178.88/year plan

The merchant uses the higher plan (€335.76) until their renewal date, so you’re paid for that usage period. The downgrade doesn’t take effect until the next cycle.

Note on Partner Dashboard: Your Partner Dashboard will show all subscription changes and cancellations on the day the merchant approves them, but the actual billing behavior (when charges apply and what the merchant pays) follows the STANDARD rules above.