Handle Shopify subscription contract billing attempts and dunning via the Subscriptions API

In-depth guide

Steps

1. Listen for the subscription_billing_attempts/failure webhook; the payload includes subscription_contract_id, error_code, and billing_attempt_id
2. Query the failed billing attempt with GET /admin/api/2025-07/subscription_billing_attempts/BILLING_ATTEMPT_ID.json to retrieve error_code and error_message
3. Trigger a new billing attempt after a delay using POST /admin/api/2025-07/subscription_billing_attempts.json with subscription_contract_id in the body
4. If the card is declined, send a payment update URL to the customer by generating a payment update URL via subscriptionContractUpdate with a new paymentMethodId, or redirect to the customer portal
5. After receiving subscription_billing_attempts/success webhook, confirm the resulting order_id is present in the payload and fulfill accordingly
6. Set a maximum retry count in your own logic — Shopify does not automatically retry failed billing attempts; your app owns the dunning cadence