Clarifying app_subscriptions/update webhook behavior in the billing system

Shopify App Store
1

Hi everyone, I’m looking for clarification on how the app_subscriptions/update webhook behaves in production. Specifically:

  1. IDs & billing cycles
  • In a live environment, do the subscription ID and cycle remain the same across updates, or can either change?
  1. Webhook payloads vs. test behavior

  • In production, should we expect the same sequence we see in tests (e.g., status of payload 1: CANCELLED and status of payload 2: ACTIVE)?

  • Will the payload include information about prorated or deferred charges?

  1. Tracking cycles best practices
  • Is there a recommended way to track the current billing cycle via the Shopify API? Or is it better to maintain this state on our side (e.g., with a scheduled job/cron) and reconcile from webhook events?
1 Like
2

If anyone else stumbles across this, I’ve managed to figure out a few things:

  1. The billing cycle in live behavior stays the same. There are two examples of this in other posts here (link1, link2).
  2. In the replacement behavior of the appSubscriptionCreate request,and in the docs, I still haven’t found clear information about how prorated or deferred charges are handled.
  3. However, through the billing object, or with a simple GraphQL query, you can retrieve the relevant billing dates and keep them up to date yourself.
3

Thanks for sharing your findings.

When using replacement behaviour, the subscription in the API will change at the time the merchant accepts the plan change since it’s not possible to have 2 subscriptions at the same time. The replacement is specifically for when the new billing is applied.

If it’s deferred to the next billing cycle, the merchant will pay the new charge at the start of the next billing cycle.

If the replacement is immediate, then the merchant will receive the standard proration or deferral behaviour.

4

Hello, thanks for your response.

Sorry for the misunderstanding, my wording wasn’t clear. What I meant to ask is: when a subscription change results in prorated or deferred charges, will the deferred/prorated amount be included in the app_subscription/update webhook, or do I need to calculate it myself?

I’m testing with Bogus and I’m not seeing any difference in the price even when I change the replacment behavior, so I’m unsure what to expect.

5

Thanks for the clarification. The webhook is going to return the value of the subscription, not the billing specifics.

For tracking the proration and deferral behaviour, you can find that in the partner API Transaction - Partner API

6

Thank you very much for your reply, it was really helpful.

If you don’t mind, I have two more questions:

  1. From what I understand, the app_subscription_update webhook only fires when a subscription changes, not when a payment is due. Is that correct?

  2. Is there a better Shopify-native way to track currentPeriodEnd instead of relying on cron jobs?

Thanks again for your help!

7

Hey @nisgia, the APP_SUBSCRIPTION_UPDATE webhook should fire each billing cycle when the current billing cycle changes.