We are designing an application that will have recurring application charges every month (30 days interval). Let’s assume we have three plans: Basic, Advanced and Pro. We understand how to create an app subscription with appSubscriptionCreate for the initial install of the application.
However, we have some questions regarding upgrading and downgrading plans:
- If the store is currently on Basic and they choose to upgrade to Advanced mid-cycle, how do we ensure that the billing cycle flow will remain the same (e.g. if they upgraded 20 days in the first billing cycle, how do we keep the end of this billing cycle after 10 days)? We also want to charge them instantly the value of the Advanced plan - the value of the Basic plan (as if they started with the Advanced in the first place). Will the replacementBehavior set to STANDARD be enough to keep it the same, if we change the price of the plan and add a discount?
- If the store is currently on Advanced and wants to downgrade to Basic, can we use the replacementBehavior set to APPLY_ON_NEXT_BILLING_CYCLE to make sure that they will charged with the Basic plan’s value on the start of the next billing cycle, and keep the billing cycle flow the same?
1 Like
Hey @WhitestRabbit
For mid-cycle upgrades, replacementBehavior: STANDARD handles exactly what you described. Your original billing cycle dates will preserved while calculating prorated charges, so if they upgrade 20 days into a 30-day cycle, the billing cycle end stays the same and they’re charged the prorated difference immediately. No manual discounts needed.
For downgrades, APPLY_ON_NEXT_BILLING_CYCLE is perfect for keeping merchants on their current higher-tier plan until the cycle ends. The Advanced plan continues running with full access, no credits are issued, and the Basic plan only kicks in at the next billing cycle start. This keeps your billing timing consistent while letting merchants get full value from what they already paid for.
Here’s the subscription billing documentation with the specific mechanics, and the replacement behavior enum reference covers both scenarios you outlined.
Thank you for this response! The thing is, we notice that the new app subscription has a different currentPeriodEnd timestamp from the previous app subscription, even if we use replacementBehavior: APPLY_ON_NEXT_BILLING_CYCLE. Are we supposed to keep track of the billing cycles end dates on our own, or is there some other attribute we should we be looking for? We are experimenting with test subscriptions, of course.
Thanks for getting back to me. This is a limitation with tests in the Billing API. It doesn’t actually create a billing record, making the replacement behaviour a bit hard to test.
So we can assume that in production, our app will work as expected if we do upgrades and downgrades as we described (in upgrade with replacementBehavior: STANDARD, no manual discount needed; in downgrade with replacementBehavior: APPLY_ON_NEXT_BILLING_CYCLE)?
Yes, exactly. I find our merchant facing help docs do a pretty good job of explaining this further (if it helps: https://help.shopify.com/en/manual/your-account/manage-billing/billing-charges/types-of-charges/third-party-charges/app-charges )
I just want to note as well, if you aren’t planning on using usage charges, the behaviour you are looking for is standard with Managed billing. That would save you from having to use the Billing API at all.
1 Like
Thank you so much, this helped immensely.
1 Like
One last question, assuming we proceed with managed app pricing!
Concerning the initial app subscription, we know how to redirect the merchant to the plan selection page, as mentioned in the Managed App Pricing documentation.
Once the merchant has subscribed, and can now fully access the application, are we obliged to show them an unsubscribe button/link in the pages of our app? Will the merchant be able to see a similar action button in the settings of the application (Settings > Apps & Sales Channels)? Or will they have to uninstall the app entirely, to unsubscribe from the app?
Hey @WhitestRabbit,
With managed app pricing, you’re not required to provide unsubscribe buttons within your app interface. However, adding cancellation/downgrade controls in your app UI can improve user experience.
Downgrade buttons won’t appear in the admin UI outside of your app UI.