I’m building a Shopify app using recurring app charges (AppSubscription via GraphQL).
I want to know what if a merchant’s card expires or a payment fails
Does Shopify Mark the App Subscription cancelled? and if it does then how do i capture that event so that i can mark the subscription cancelled in my App likewise.
Hi @Shopping_IQ
When a merchant’s Shopify billing fails (for example, their card expires or they stop paying their Shopify subscription), Shopify does not usually mark your AppSubscription as CANCELLED. Instead, the subscription status becomes FROZEN, which means the recurring app charge is on hold due to non‑payment and will automatically re‑activate once the merchant resolves the billing issue. The CANCELLED state is a terminal state and is used for explicit cancellations (your app calling appSubscriptionCancel, app uninstall, or a new subscription replacing an old one), not transient payment failures. See AppSubscriptionStatus for the full list of statuses.
To detect and react to these situations in your app, the simplest and most robust method is to query the Admin GraphQL API for the current subscription status whenever you need to make an access decision. Using currentAppInstallation, you can fetch allSubscriptions { edges { node { id name status } } } and gate your features based on status: treat ACTIVE as fully paid, FROZEN as temporarily suspended (show a “billing issue” message), and CANCELLED/DECLINED/EXPIRED as having no valid subscription and show your paywall / re‑subscribe flow. This polling approach keeps you in sync even if the exact payment failure reason (expired card vs other) isn’t directly exposed to you.
If you want more event‑style insight into billing changes, you can also use the Partner GraphQL API to read app billing events via App.events with types from AppEventTypes, such as SUBSCRIPTION_CHARGE_FROZEN, SUBSCRIPTION_CHARGE_UNFROZEN, and SUBSCRIPTION_CHARGE_CANCELED. You’d call this from a backend job, map events to shops, and update your own subscription table. In practice, many apps combine both approaches: Admin GraphQL for real‑time gating on each request, and Partner API events for background reconciliation and analytics.
1 Like