App Usage Subscription questions

[barnabycollins]

Hey there,

I'm currently implementing the Shopify billing API. I have successfully got an app usage subscription working, but I have some related questions that I can't find solutions to and need answered ASAP.

The first question is: what are the payload types on APP_SUBSCRIPTIONS_UPDATE and APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT webhooks? I can't find this documented anywhere.

Secondly, along the same lines, when is APP_SUBSCRIPTIONS_UPDATE fired?

How can I get information on non-current billing periods? Is the only way to extrapolate by using +/- 30 days, or is there a safer option?

Finally, what happens when the customer pays for a month of usage? Is a webhook fired? How can I get information on the payment to, eg, verify that they've paid the expected amount?

Also, for future questions, what is the recommended way of getting support on technical queries? Over the past few weeks I've tried email, partner live chat, Discord and Slack and had no useful responses from any. Email and live chat directed me to Discord / Slack, and the Discord and Slack communities seem to have minimal Shopify presence. If the forum is the correct place to ask these questions just let me know and I'll stick to it from now on.

Thanks in advance!

[Shayne]

 I'll address each of your questions one by one:

Payload types for APP_SUBSCRIPTIONS_UPDATE and APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT webhooks:

The payload types for these webhooks are not explicitly documented (they probably should be), but they generally follow the same structure as the AppSubscription object. You can find the AppSubscription object details here: https://shopify.dev/docs/api/admin-graphql/2022-07/objects/AppSubscription

When is APP_SUBSCRIPTIONS_UPDATE fired?

APP_SUBSCRIPTIONS_UPDATE webhook is triggered when there's an update to the app subscription, such as a change in the subscription plan, cancellation, or resuming a previously cancelled subscription.

Getting information on non-current billing periods:

Currently, the Shopify Billing API does not provide a direct way to fetch information on non-current billing periods. Your approach to extrapolate using +/- 30 days is a viable option. You might also consider storing the billing period information in your own system when you receive the relevant webhook events to avoid doing this calculation.

What happens when the customer pays for a month of usage?

When the customer pays for a month of usage, you can listen to the aforementioned webhooks to get notified about charges being created, updated, or deleted. The webhook will include the charge details, allowing you to verify the payment amount. 

Recommended way of getting support on technical queries:

The Shopify Community forums are the best place to ask technical questions and get support from the Shopify team and other developers.

[barnabycollins]

Hey Shayne,

Huge thanks for this; your answers are very helpful.

Regarding webhook payloads - yes, I'd guessed they might return an AppSubscription, but I wasn't sure where I would find it in the webhook object. However, Tim Fletcher on Slack did respond to my question after I'd started this thread, mentioning that I could manually trigger test webhooks using the Shopify CLI, which was useful. I think these are REST webhooks though; is the format the same for webhook subscriptions enrolled with the GraphQL API? I also noticed that the list of CLI-supported topics doesn't seem to include APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT, so if you have any more information on that webhook's payload that would be amazing.

For others coming across this thread, it seems like the app_subscriptions/update webhook body (as of the 2023-01 API) has the following format, based on my brief testing using the CLI:

{
  app_subscription: {
    admin_graphql_api_id: 'gid://shopify/AppSubscription/1029266957',
    name: 'Webhook Test',
    status: 'PENDING',
    admin_graphql_api_shop_id: 'gid://shopify/Shop/548380009',
    created_at: '2021-12-31T19:00:00-05:00',
    updated_at: '2021-12-31T19:00:00-05:00',
    currency: 'USD',
    capped_amount: null,
  },
};

You mention later that the webhooks (presumably APP_SUBSCRIPTION_UPDATE) return information on charges, however, but I'm not seeing that data listed on the test webhook payload, or on the AppSubscription data model. I assume this will involve the UsageChargeApplied and/or AppUsageSale events / models, but I'm not sure where that data will appear and I can't find a way to mock it with the CLI. Currently the only way I have to find this out for sure is to wait 30 days on my test subscriptions, so is there any more information you can provide on this?

Also, have you got a more explicit list of what events will trigger APP_SUBSCRIPTION_UPDATE? Otherwise, Is it safe to assume that it gets fired whenever anything remotely related to the relevant subscription happens?

Finally, a quick question on the APP_SUBSCRIPTIONS_APPROACHING_CAPPED_AMOUNT event - I've seen that the merchant-facing documentation mentions that merchants will receive an email when a subscription reaches 90% usage, but I've not seen that fired during my (admittedly fairly limited) testing. Will Shopify automatically send an email, or is it down to us to fire an email over to the merchant? We have an email model already created for this purpose, but I wanted to check we wouldn't be double-emailing them before enabling it.

Thanks again for your quick and helpful response; it's much appreciated.

[barnabycollins]

Hey @Shayne - sorry to poke, but I wanted to make sure you'd been notified by my other reply. I'm not sure if I posted it as a reply to your post or not, but I had a few more questions.

Also, another question: is it correct that AppSubscription.currentPeriodEnd shows the end of the last billing period, rather than the end of the current one? If so, that could be made clearer as I expected it to be populated with the end of the current billing period (ie, 30 days after the subscription was confirmed in the case of a newly-created subscription).

[Shayne]

Hi!

> You mention later that the webhooks (presumably APP_SUBSCRIPTION_UPDATE) return information on charges, however, but I'm not seeing that data listed on the test webhook payload, or on the AppSubscription data model.

You can use the ID that you got back to get the AppSubscription with associated LineItems and UsageCharges. It's rare that the Webhook directly returns multiple layers of child resources — you'll sometimes need to query for information to get everything that you need. The actual amount that gets charged is under the AppUsageRecord

>  Is it safe to assume that it gets fired whenever anything remotely related to the relevant subscription happens?

Pretty much. You can DM me if there are situations where you're not seeing it fire and I'll do my best to fix them.

> I assume this will involve the UsageChargeApplied and/or AppUsageSale events / models, but I'm not sure where that data will appear and I can't find a way to mock it with the CLI. Currently the only way I have to find this out for sure is to wait 30 days on my test subscriptions, so is there any more information you can provide on this?

This is a good point. It's not the easiest to test — I'll take this back and see if we can make some changes to improve the experience.

> I've seen that the merchant-facing documentation mentions that merchants will receive an email when a subscription reaches 90% usage, but I've not seen that fired during my (admittedly fairly limited) testing. Will Shopify automatically send an email, or is it down to us to fire an email over to the merchant?

This is something that we send, you don't have to worry about sending an email to the merchant.

[barnabycollins]

Hi @Shayne - thanks for your answers and clarifications 🙂 this is a big help. I hate to keep going with more questions, but we're nearly there!!

Regarding the times when APP_SUBSCRIPTION_UPDATE gets fired - the main case I've come across where it doesn't seem to fire is in the case of the app getting uninstalled whilst the subscription is active. Incidentally, what actually is the behaviour when this happens - presumably the merchant still gets billed for any outstanding usage but no further usage gets added?

Regarding the notifications relating to payments - is there any chance you could provide any example payloads and/or queries, as of API 2023-01? I can't really afford to wait a month to see what happens as we need to push this to production and we have other pressing work to do.

Finally, could I get an explicit confirmation of the behaviour surrounding AppUsageSubscription.currentPeriodEnd? I see you liked the post above relating to this, but I wanted to confirm exactly how it works as I've seen conflicting messages. The most common view from what I've seen seems to be that it doesn't update on test subscriptions but does represent the end of the current period (ie, the point in the future at which the next payment will be taken) in 'real' subscriptions - is this correct? If so, I'd have said it's somewhat problematic that test subscriptions don't match the behaviour of production subscriptions but I'd at least be content in knowing that my current implementation (which assumes the behaviour above) is correct for real subscriptions.

I do really appreciate your help; thank you - I really just need to get the payment-handling code done and then I think I'll be finished, so I just need some final clarification in these areas.

[barnabycollins]

Hi @Shayne - sorry to poke, but could you respond to the questions on my most recent post?

[barnabycollins]

Hey @Shayne - again, sorry to keep tagging you, but I'd really like a resolution to this so I can proceed with my implementation. We already have our app fully working and approved on other store platforms and this is the major roadblock stopping us releasing on Shopify. If we don't get this resolved, our only option will be to focus on implementation for other store platforms and explain to our ecommerce customers that we don't support Shopify for this reason.

Thanks, and sorry again!

[Shayne]

Regarding the times when APP_SUBSCRIPTION_UPDATE gets fired - the main case I've come across where it doesn't seem to fire is in the case of the app getting uninstalled whilst the subscription is active. Incidentally, what actually is the behaviour when this happens - presumably the merchant still gets billed for any outstanding usage but no further usage gets added?

 Correct. Existing billings will still be processed but no additional charges will be applied.

Regarding the notifications relating to payments - is there any chance you could provide any example payloads and/or queries, as of API 2023-01? I can't really afford to wait a month to see what happens as we need to push this to production and we have other pressing work to do.

---

Here's an example of the body:

admin_graphql_api_id: gid://shopify/AppSubscription/1029266951,
admin_graphql_api_shop_id: gid://shopify/Shop/548380009,
capped_amount: null,
created_at: 2021-12-31T19:00:00-05:00,
currency: USD,
name: Webhook Test,
status: PENDING,
updated_at: 2021-12-31T19:00:00-05:00

 
You can test webhooks using the CLI trigger specified here.

It's a relatively new feature, but very cool!

Finally, could I get an explicit confirmation of the behaviour surrounding AppUsageSubscription.currentPeriodEnd? I see you liked the post above relating to this, but I wanted to confirm exactly how it works as I've seen conflicting messages. The most common view from what I've seen seems to be that it doesn't update on test subscriptions but does represent the end of the current period (ie, the point in the future at which the next payment will be taken) in 'real' subscriptions - is this correct? If so, I'd have said it's somewhat problematic that test subscriptions don't match the behaviour of production subscriptions but I'd at least be content in knowing that my current implementation (which assumes the behaviour above) is correct for real subscriptions.

---

Yes, the intent is that AppSubscription.currentPeriodEnd represents "The date and time when the current app subscription period ends." I agree that test subscriptions behaving differently is problematic, but you can depend on the documented behaviour for your production app.

[barnabycollins]

Hi @Shayne - thank you so much for your help!! This is all really useful information; thank you. The CLI is indeed cool, thanks for highlighting that 🙂

One final line of questioning: How do I get the historic and current transactions associated with a particular subscription? Are they attached to the AppSubscription that I can get from the API, or should I be looking elsewhere? Is there a webhook that gets fired when transactions are created or updated? And what's the data model for these transactions? If I've just missed something then please let me know, but I couldn't find something that was clearly an app subscription transaction on the documentation or anywhere in the AppSubscription data model.

Once I have this information I should have everything I need!

Thanks 🙂

[danhho]

Hi @barnabycollins , sorry keep tagging with you, but can you confirm for me that APP_SUBSCRIPTION_UPDATE will triggered when shopify automatic charge successfully after 30 days?
I have same problem with you
Thanks alot.