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://help.shopify.com/en/manual/your-account/manage-billing/billing-charges/types-of-charges/third-party-charges/app-charges#app-prorating-upgrades-downgrades
Is a scenario with Shopify managed pricing and a downgrade mid cycle, the subscription changes immediately, but their billing change is defered until the start of the next cycle. You would need to account for this within your app logic.
Alternatively, there is the billing API where you have a little more control over the replacement behaviour. You can specify immediately in instances of downgrades and the merchant would then be granted credits for the remaining balance. AppSubscriptionReplacementBehavior - GraphQL Admin