App subscription plan upgrades/downgrades

[KyleG-Shopify]

Hey @Min_Liu, part of what you’re seeing is a dev store limitation. Test subscriptions don’t create real billing records, so the deferral doesn’t work there. Same limitation I mentioned earlier in this thread about test charges.

One thing to know for production though: the subscription object in the API updates immediately when a merchant downgrades. A merchant can only have one active subscription at a time, so when they accept the downgrade, activeSubscriptions reflects the free plan right away. The deferral is specifically about billing. The merchant has paid through currentPeriodEnd, so use that timestamp to gate feature access instead of the subscription name.

Another developer ran into this exact scenario with managed pricing and I walked through it in detail here:

[test store]Using the managed price, after selecting free, the subscription update was received immediately, and the plan changed to free

Thanks for sharing that. I agree, the language used in the docs can be confusing. In these cases, it’s useful to consider the billing period separate from the app subscription. Its currently only possible for a merchant to have a single app subscription at a time, so when a merchant downgrades and accepts the change, their plan is changed immediately and that is what is reflected in the API, but their billing cycle remains the same. The merchant docs do a better job of explaining this: https:…