New WebHooks and App Events for App Usage Spending Limits and Changes to balanced_used
API
Effective July 01, 2022
Action required
On July 31st 2022 we will be introducing App Usage Spending Limits to provide flexibility for merchants to control the usage charge limit per billing cycle from their Shopify admin. Developers no longer need to set a "one size fits all" app usage capped amount that is difficult to meet a variety of merchants' needs.
Merchants Can Self-Serve Increasing Their Subscription's cappedAmount
As of July 31st 2022 Merchants will be able to increase the cappedAmount associated with a subscription that has usage pricing. Partners are advised to listen to the app_subscription/update webhook to stay notified when Merchants update their capped amounts. For instructions on how Merchants will be able to update their cappedAmount visit the help center
App Usage Webhook Notifications
As of GraphQL Admin API version 2022-07, app developers offering usage-based pricing should subscribe to new webhook updates in advance of the roll out of App Usage Spending Limits. Developers can receive notifications when merchants update their App Spending Limits, which is also the capped_amount by creating a webhook subscription through the Admin Graphql API to the app_subscriptions/update topic.
Once merchants update their App Spending Limits, developers may need to make updates to their application to allow merchants to incur additional usage charges.
Learn more about Admin Graphql API webhooks here.
Important update about balance_used endpoint for app usage charges
The balance_used endpoint in the App Usage Pricing API now shows the running total usage charges for the entire billing cycle. Previously, there was an issue where the usage charge running total, presented on the balance_used field, resets when a new recurring charge with usage-based pricing is accepted by the merchant. Note that the issue only applied to the value being presented in the balance_used field and usage charges were not able to exceed the capped_amount in a cycle.
Going forward, the balance_used endpoint will always show the total usage charge balance for the billing cycle, which is reflective of what merchants see in the Shopify Admin about their current App Spending Limits.