How to Set Up Dunning for Shopify Subscriptions
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.
What dunning does
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.
Payment failure vs. inventory failure
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.
Where to find dunning settings
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.
Configuring payment failure settings
Payment failure dunning has three controls:
- **Retry attempts:** The number of times subZwallet will retry charging the customer after the initial failure. Set this between 3 and 4 for most stores.
- **Days between retries:** How many days to wait between each retry attempt. Three days is the standard interval — long enough for customers to fix their payment method, short enough to keep the recovery window tight.
- **Final action (On failure):** What happens after the last retry fails. Choose one: **Skip billing cycle** (subscription stays active, next charge happens on the regular schedule), **Pause subscription** (billing stops until you or the customer resumes), or **Cancel subscription** (contract ends permanently).
Configuring inventory failure settings
Inventory failure dunning has four controls:
- **Retry attempts:** How many times to retry after an inventory allocation failure.
- **Days between retries:** How long to wait between retries. Match this to your restocking cadence — if you restock weekly, set retries 7 days apart.
- **Final action (On failure):** Same three options as payment failure: Skip, Pause, or Cancel.
- **Notification frequency:** How often subZwallet notifies you about inventory failures. Choose **Immediately** (get alerted on every failure so you can restock urgently), **Weekly** (summary digest), or **Monthly** (for low-volume stores or items with long restock cycles).
Example configurations
**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.
What happens after the final action
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).
For paused and cancelled outcomes, pair dunning with your email templates to notify the customer. A well-timed "your subscription was paused — click here to update your payment method" email recovers a meaningful percentage of otherwise-lost subscribers.
Handling individual failed billings manually
Dunning handles automatic retries across all contracts, but you can intervene on any single contract at any time. Open the contract in **Manage Subscriptions**, find the failed billing, and choose: **Retry** (charge the customer again immediately), **Skip** (move to the next billing cycle), or **Ignore** (leave it in failed state and let dunning continue its scheduled retries).
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.
Saving and applying changes
Click **Save** on the dunning settings page. New settings take effect immediately for any billing that fails after you save. Billings already mid-retry continue under the settings that were active when they first failed — subZwallet does not retroactively change retry schedules for in-flight failures.
Next steps
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.