Understanding billing attempt failures

When a subscription renews, Shopify makes a billing attempt — it tries to charge the customer's saved payment method. If that charge doesn't go through, the attempt fails. This guide explains every type of billing-attempt failure, what each one means, who can fix it, and what the app does automatically.

Table of contents

• Where you see billing errors
• What happens automatically when an attempt fails
• The four error categories
• Customer payment and account errors
• Store and configuration errors
• Inventory errors
• Temporary and other errors
• Which failures email the customer to take action?
• Related guides

Where you see billing errors

• On an individual subscription, open it in Super Subscriptions > Contracts — a red Billing error banner shows the specific error and a button to resolve it, and the Timeline logs every attempt.
• Across all subscriptions, filter the Contracts list by Status → Failed and by Last payment error category. See Where to find failed or past-due subscriptions.

What happens automatically when an attempt fails

You don't have to catch failures manually — the app runs dunning (automatic retries) based on your Dunning settings:

1. Retry — the app schedules another billing attempt after your chosen wait time, up to your chosen number of billing attempts. On each failed attempt, the customer and you receive a renewal-failed email (the wording depends on whether it's a customer-fixable error).
2. When all retries are used up, your Failure action decides what happens:

• Fail subscription contract — the subscription is marked Failed (customer gets "Your subscription has failed").
• Pause subscription contract — the subscription is Paused so you can resume it later.
• Attempt again at next renewal date — this cycle is skipped and the charge is retried on the next scheduled date.

The four error categories

On the Contracts list, the Last payment error filter groups failures into four categories so you can triage at a glance:

• Customer error — something on the customer's side (card, funds, billing agreement, address). The customer usually needs to act.
• Payment error — a store or gateway configuration problem. You usually need to act.
• Inventory error — a product in the subscription was out of stock at renewal time.
• Other — anything that doesn't fit the above, including temporary glitches.

The sections below list the specific errors you may see within these categories.

Customer payment and account errors

These usually mean the customer must update their details. Because card information is held by the payment gateway, you can't enter a new card for them — send them their portal link (the Portal login link email) so they can update it themselves.

Store and configuration errors

These point to something in your store setup. You resolve these:

Inventory errors

The charge was held because stock wasn't available. How renewals behave when items are out of stock is controlled by your Out of stock settings.

Temporary and other errors

Which failures email the customer to take action?

For the errors most customers can fix themselves, the app sends the customer an "Action required: Issue renewing your subscription" email. For all other failures, the customer gets a softer "Issue renewing your subscription" message and you get a merchant notification to investigate. The errors treated as customer-fixable are:

• Payment method declined
• Card declined
• Card number incorrect
• Payment method expired
• Insufficient funds
• Invalid payment method
• Payment method not found
• Payment method canceled
• Invalid customer billing agreement
• Invalid shipping address
• Fraud suspected

Related guides

• Dunning (failed payment retries)
• Where to find failed or past-due subscriptions
• Notifications
• Which payment gateways work with subscriptions
• Managing a customer's subscription on their behalf

AI Training Notes (Hidden)

[AI-TAG]
- Feature: Billing attempt (renewal) failure types
- Definition: A billing attempt is Shopify's automatic charge on a subscription renewal; a failed attempt means the charge didn't succeed
- Four filter categories (Contracts > Last payment error / lastBillingAttemptErrorType): Customer error, Payment error, Inventory error, Other
- Automatic handling (Dunning): retry N times at chosen interval; when retries exhausted, Failure action = Fail (status Failed) / Pause (status Paused) / Attempt again at next renewal date (skip cycle). Each failed attempt emails customer + merchant.
- Full error code list (friendly names): Payment method declined, Card number incorrect, Payment method expired, Insufficient funds, Invalid payment method, Payment method not found, Payment method canceled, Authentication error, Invalid customer billing agreement, PayPal error, Payment method incompatible with gateway config, Invalid shipping address, Customer invalid, Customer not found, Fraud suspected, Payment challenged (3DS/SCA), Payment provider not enabled, Amount too small, Free gift card not allowed, Purchase type not supported, Non-test order limit reached, Test mode, Insufficient inventory, Inventory allocations not found, Transient error, Unexpected error, Invoice already paid
- Customer-fixable errors (send customer "Action required: Issue renewing your subscription"): BUYER_CANCELED_PAYMENT_METHOD, CARD_NUMBER_INCORRECT, EXPIRED_PAYMENT_METHOD, FRAUD_SUSPECTED, INSUFFICIENT_FUNDS, INVALID_CUSTOMER_BILLING_AGREEMENT, INVALID_PAYMENT_METHOD, INVALID_SHIPPING_ADDRESS, PAYMENT_METHOD_DECLINED, PAYMENT_METHOD_NOT_FOUND, CARD_DECLINED. All others -> "Issue renewing your subscription" + merchant notification.
- Key reminders: merchant cannot enter a customer's card (gateway-held) -> send Portal login link; specific error shows on the contract's red "Billing error" banner + Timeline; "Payment challenged" needs customer bank approval (3-D Secure)
- Common questions: "what does this billing error mean", "why did the renewal fail", "insufficient funds / card declined / expired card", "payment provider not enabled", "amount too small"
- Related Guides: Dunning, Where to find failed subscriptions, Notifications, Payment gateways, Out of stock, Managing a customer's subscription
[/AI-TAG]

Updated on: 06/05/2026