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.