Working of AppSubscriptionReplacementBehavior: APPLY_ON_NEXT_BILLING_CYCLE

[Piyush_Gupta]

Hi,

We have a scenario for our app, in which we want to allow the merchant to downgrade their current plan subscriptions. But we want that when they select to downgrade, that downgrade should be applied from the next billing cycle onwards and current active plan should remain as it is till next billing cycle.

We came across the APPLY_ON_NEXT_BILLING_CYCLE - Replacement Behaviour. On testing this feature with the test charge, the current active charge is getting cancelled immediately and downgraded plan charge is shown as ACTIVE instead of being deferred to next billing cycle.

We have subscribed to the 'APP_SUBSCRIPTIONS_UPDATE'  web hook. On approving the new downgraded charge, we immediately received two web hooks callbacks. One, with the CANCELLED status for the existing ongoing plan, and second, with the "ACTIVE" status for the new downgraded plans.

Below are the queries for this scenario:

1. We want to know what is the actual working of this replacement behaviour?

2. If it replaces the current plan on next billing cycle only, then when can we expect to receive the call backs for current cancellation and new plan activation?

[logoshot]

I am experiencing the same issue with creating the APPLY_ON_NEXT_BILLING_CYCLE subscriptions. It appears that the replacement behavior is not functioning properly, as it cancels all charges and applies the new charge immediately.

[ShopifyDevSup]

Hi folks, I'm reaching out to let you know we're looking into this. I can't confirm if this is expected behaviour at the moment, but just wanted to let you know we appreciate you mentioning what you're seeing on your end here. 

I can't guarantee what the response will be, but did also want to let you know I'm confirming expected behaviour for the component based on your reports. Would anyone be willing to share a webhook subscription ID or an X-Request-ID header value from an API response from us? Could you also confirm if these are real charges or test charges where the behaviour is occurring? This info would help us pull some relevant API calls in our logs so we can troubleshoot more effectively. 

Hope to hear from you soon - thanks again for bringing this up to us. 

Al | Shopify Developer Support

[shogun_hugo]

We are also seeing this in Aug 2023. Any thoughts, Shopify?

How can we know what yearly subscriptions are deferred vs active?

According to the documentation, with the "standard" behaviour, updates should replace the current subscription when the new subscription is more expensive. Otherwise, the replacement is deferred.

We are not seeing this. Instead, it seems that Shopify "cancels" the current yearly subscription and adds a new "active" one, even when that amount is lower. Then the billing period carries over to the new one. This can be repeated many times.

This is what happened after I downgraded a running $25 yearly plan to a $17 one in production:

{"id"=>30433181995,
  "name"=>"build",
  "price"=>"17.00",
  "billing_on"=>"2024-08-11",
  "status"=>"active",
  "activated_on"=>"2023-08-14",
...

{"id"=>30432756011,
  "name"=>"grow",
  "price"=>"25.00",
  "billing_on"=>nil,
  "status"=>"cancelled",
  "activated_on"=>"2023-08-14",
  "test"=>false,
  "cancelled_on"=>"2023-08-14",
...

Hence, we can't tell which yearly subscription should remain active. Should the paid yearly subscription remain "active"  until the end of its billing cycle, and any deferred subscriptions have a new state, e.g. "deferred"?

What do you advise Shopify?

How did you tackle this @Piyush_Gupta @John_Hardin  ?

[John_Hardin]

Production or Test? Test subscriptions were known to behave this way because they did not actually implement any of the billing period logic for test subscriptions. You can't actually test anything periodic without using a paid account and a live subscription (which requires an approved app).

I haven't heard whether that has been fixed yet, but my attention has been elsewhere for the last couple of months.

[shogun_hugo]

These were live charges, as you can see: "test"=>false,

We also realized that test charges do not follow the live behaviour. Which defeats the purpose of testing. That has been raised to Shopify before.

[bluezwei]

I encountered the same issue.

Under the STANDARD scenario, if a user's annual subscription is converted to a monthly one, the returned active subscription name changes immediately, but currentPeriodEnd (GQL) and billing_on (RestApi) still maintain the date a year later.

This result is meaningless.

My expectation is that before the annual subscription ends, the returned subscription should still be the annual one, and it should change to a monthly subscription only after the period ends.

The logic Shopify uses to handle this is confusing.

[John_Hardin]

We are also experiencing this behavior.

In addition, the billing period gets reset as well - normally with a "takes place immediately" subscription change the prior billing period cadence is retained. This time the billing period got reset to the approval date.

What's up, Shopify?

[shogun_hugo]

Shopify – These are the mains issues:

• Live and test charges need to act the same. We shouldn't be required to use live charges to test the replacement behaviour. That defeats the purpose of having test charges.
• Charges are not a useful model for us to track subscriptions/plans. They have distinct purposes. Shopify only cares about when charges are due. We care about which plans are active and which ones are deferred.
• Documentation is contracting itself.

Your documentation states that:

The existing recurring app charge is canceled and replaced by the new charge when the merchant approves it.
…
If a merchant switches from an annual plan with a higher price to an annual plan with a lower price, or from an annual plan to a 30 day plan, then the charge for the new plan is deferred until the current plan’s subscription cycle is complete.
…

Here, it's mentioned that charges are replaced immediately, and it's the billing of the charge that is deferred. That's what we are seeing.

However, the GQL documentation states:

Cancels the merchant’s current app subscription immediately and replaces it with the newly created app subscription, with the exception of the following scenarios where replacing the existing app subscription will be deferred until the start of the next billing cycle.

Here, it's said that “replacing” will be deferred. This is confusing and incorrect. One says charges are replaced, whereas this one says it depends. It turns out the GQL documentation is incorrect. The replacement happens regardless. It’s the billing that is deferred.

[erandagan]

Same set of problems here. It's also unclear what the expected behaviour is for the following sequence of events:

January 1st: Subscribe ($10) (1)

January 3rd: Subscribe ($5) - APPLY_ON_NEXT_BILLING_CYCLE (2)

January 4th: Subscribe($15) - APPLY_IMMEDIATELY (3)

In that case, which subscription is expected to be active? What would the pro-ration rate be?

Is it:

a) Subscription (1), because subscription (3) replaces the deferred subscription (2). No proration occurs. On the next billing period, the full charge will be for subscription (3), which replaces (2).

b) Subscription (3), because it applies immediately. Proration is calculated according to the activation date of (3).

This is obviously a simplified version, but in production scenarios the combinations get a lot more complex - especially with all the edge cases in the API. 

[DanXIT]

Is this only on dev store? Cause I got the same issue on "APPLY_ON_NEXT_BILLING_CYCLE" I was expecting the status stay in "pending" until next billing cycle, but it turn out it just cancel the current one and activate it...it is quite frustrating there's no way to test out 

[firstsale]

A year and a half later, it appears this has not been resolved. Still seeing very little documentation around this area and test mode behaves the same way as described in this thread.