When a subscription billing fails — whether the customer's card is declined or a product is out of stock — your store loses revenue unless something retries that charge automatically. Dunning is the automated retry process that recovers failed billings without you or your customer lifting a finger.
Failed payments account for a significant share of subscription cancellations, and most of them are recoverable. A properly configured dunning setup in subZwallet handles retries on a schedule you define, sends the right notifications, and takes a final action when recovery is not possible.
Dunning monitors every subscription billing attempt in your store. When Shopify reports a failure, subZwallet queues automatic retries based on your configuration: how many times to retry, how long to wait between attempts, and what to do after the last attempt fails. You configure it once and it applies to all subscription contracts.
subZwallet handles two distinct failure types, each with its own retry settings, because the root cause and recovery path are different.
Understanding the difference between these two failure types matters because they require different retry strategies.
Payment failures occur when Shopify cannot process the charge. Common causes include declined cards (insufficient funds, expired card, card reported stolen), invalid payment methods, and processor errors. Shopify categorizes these through its SubscriptionBillingAttemptErrorCode system, distinguishing between soft declines (temporary issues like insufficient funds that may resolve on retry) and hard declines (permanent issues like a stolen card that will never succeed) (https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptErrorCode). Retrying makes sense here because many soft declines resolve within days — the customer gets paid, updates their card, or their bank clears a hold.
Inventory failures occur when a product in the subscription is out of stock or cannot be allocated at billing time. The charge never reaches the payment processor — it fails before that step. Retrying is useful only if you expect to restock the item. If the product is permanently discontinued, retries waste time and delay the final action.
In the subZwallet app: go to App Settings and click Dunning Settings, then click Edit. This opens the full dunning configuration page where you control both payment and inventory failure handling.
Payment failure dunning has three controls:
Out-of-stock renewals have their own settings. The order is kept as owed and retried, so the customer still gets it once you restock. There are four controls:
The alert center lists subscriptions that failed or are at risk, and the products blocking them ("restock needed"), so you can see which items to restock first. Failed payments also have their own tab in the Manage Subscriptions list.
High-volume consumables store (supplements, coffee, pet food): Payment failure — 4 retries, 3 days apart, pause on final failure. Inventory failure — 2 retries, 7 days apart, skip on final failure, notify immediately. Pausing on payment failure gives customers time to update their card without losing their subscription. Skipping on inventory failure keeps the subscription alive and charges them on the next cycle when stock is replenished.
Premium subscription box (quarterly, high AOV): Payment failure — 3 retries, 5 days apart, pause on final failure. Inventory failure — 3 retries, 5 days apart, pause on final failure, notify immediately. Wider retry spacing matches the higher order value — customers may need more time to ensure funds are available. Pausing on inventory failure prevents shipping an incomplete box.
Low-price replenishment (razors, vitamins under $20): Payment failure — 3 retries, 2 days apart, cancel on final failure. Inventory failure — 1 retry, 3 days apart, skip on final failure, notify weekly. Faster retries and cancellation on failure make sense when the order value is low and customer reacquisition cost is minimal.
When all retries are exhausted, subZwallet executes your chosen final action and updates the contract status. If you chose Skip, the contract remains active and the next billing date stays on schedule. If you chose Pause, the contract moves to a paused state — billing stops but the subscription is not deleted, and either you or the customer can resume it. If you chose Cancel, the contract status transitions to cancelled and billing ends permanently (https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts).
Each failed payment and retry is paired with a branded email that links the customer to a secure card update. Turn the templates on or off and edit them in Email templates (or let Klaviyo send them if it is connected).
Dunning handles automatic retries across all subscriptions, but you can step in on any single one. Open it from the Failed tab in Manage Subscriptions and choose what to do: send the customer a payment-update email, Skip the order, or use Process now to bill the order once the customer has updated their card. Otherwise, dunning keeps retrying on schedule.
Manual intervention is useful when a customer contacts support about a failed charge, when you know a payment method has been updated and want to retry immediately, or when a specific contract needs different handling than your global dunning rules.
Click Save on the dunning settings page. The new settings apply to billings that fail after you save.
For a full recovery strategy beyond retry settings, see the Involuntary churn dunning recovery playbook. To customize the emails customers receive during dunning, see Email templates. For global app configuration, see App settings. To manage individual subscriptions and their billing status, see Manage subscriptions.
For the strategy behind these settings, read our guide to [failed payment recovery](/blog/failed-subscription-payments-dunning-guide).