ApplyOnNextBillingCycle not working as expected

Shopify Apps
,

Topic summary

Main issue: Controlling downgrade timing and proration via BillingReplacementBehavior (e.g., ApplyOnNextBillingCycle) did not work as expected in tests. A user’s flow—users start on a usage-based plan, upgrade to a monthly subscription with bundled usage, then downgrade—resulted in immediate downgrade from monthly back to usage-based, with no apparent control over proration.

Key clarification: In Billing API test mode, downgrade behavior does not match production. A referenced prior thread indicates test mode may not reflect real-world handling of replacement behavior.

Implications: The observed immediate downgrade and lack of proration control may be artifacts of test mode. Achieving the intended pricing might not require hybrid plans if production honors ApplyOnNextBillingCycle as designed.

Status: No confirmed resolution yet. Action items: Review the linked thread; validate behavior in production (or a staging environment mirroring prod) to confirm actual downgrade timing and proration. Open question: Whether production reliably applies replacement on the next billing cycle.

Summarized with AI on December 17. AI used: gpt-5.
1

I am testing BillingReplacementBehavior and had expected to be able to control when downgrades take place or at least to be control how the downgrade / cancellation is prorated.

I had wanted to use an entry level usage based plan and then let users upgrade to month subscriptions with a usage limit bundled into the subscription. After testing, downgrading from the monthly plan to the usage based plan happen immediately and I am not able to control how the prorating work. I really wanted to avoid creating more complex hybrid subscription + usage plans, but I think this may be the only way to achieve the pricing structure I was after.

Anyone find a way to accomplish this or similar?

2

If you are using test mode for the billing API, unfortunately it does not reflect the real behaviour when downgrading.

See previous threads: https://community.shopify.com/post/2183456

1 Like
3

Thanks! I searched around for previous threads on this. Not sure how I missed that one.

Billing seems like one of the more important areas of the API to have complete and consistent test coverage of between test and prod…

1 Like
4

That link is broken. I would like to see some official documentation on this.