Handle a Shopify SubscriptionContract billing attempt failure and trigger a dunning retry via the Subscriptions API
domain: shopify.dev · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Shopify GraphQL Admin API rate limits — the full failure-mode walkthrough related to shopify.dev, checked against official docs, with linked verified routes.
Steps
Subscribe to the subscription_billing_attempts/failure webhook topic in Shopify to receive real-time failure events
On receipt, parse the subscriptionBillingAttempt object to extract errorCode and nextActionUrl if present
Determine retry eligibility by checking the contract's status field via the subscriptionContract GraphQL query; do not retry if status is PAUSED or CANCELLED
Issue a new billing attempt using the subscriptionBillingAttemptCreate mutation with the contract GID and idempotencyKey set to a unique retry identifier
After a configurable number of failures, call subscriptionContractUpdate mutation to set status to PAUSED and send a dunning email with a payment update link
Known gotchas
Each subscriptionBillingAttemptCreate call requires a unique idempotencyKey; reusing a key for a retry returns the original attempt result rather than creating a new one
Shopify does not perform automatic retries for subscription billing; all dunning logic must be implemented by the app
The nextActionUrl in the failure payload is only present for 3DS-required failures and is customer-facing; it expires, so prompt the merchant to surface it quickly
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?