Shopify payment declined codes, explained for subscription merchants

Moorly guides · Updated August 2026 · 9 min read

When a subscription renewal fails, somewhere behind that failure is a decline code — the short reason the payment system recorded for why the charge didn't go through. Shopify shows what it receives from the customer's bank in the order history, and Shopify's subscription billing API records an error code on every failed billing attempt. How much of that reaches you depends on where you look — some apps show the decline reason on the failed renewal, some show it only in an aggregate report, and some do both. It is worth finding, because the code tells you what would actually recover the money — and the right responses to different codes are close to opposites.

The one distinction that matters: soft vs. hard declines

• Soft declines are temporary. The card is valid, but this attempt, at this moment, didn't go through — no money in the account, a cautious bank, a processing hiccup. A well-timed retry can recover these.
• Hard declines are permanent. The card is expired, cancelled, reported lost or stolen, or the account is closed. No retry will ever succeed — only a customer card update fixes them.

Retrying a hard decline wastes attempts and emails; sending a card-update ask for a soft decline adds friction the customer didn't need. Reading the code correctly is what our retry-schedule guide builds on.

The codes you'll actually see, by family

The names below follow the error codes Shopify's subscription billing API uses for failed billing attempts (the same reasons appear in slightly different spellings in order history and in gateway dashboards — insufficient_funds, INSUFFICIENT_FUNDS, and “insufficient funds” are the same decline).

Usually recoverable with a retry (soft)

• insufficient_funds — the most common soft decline. The account didn't have the money at that moment. Best recovered by a retry that lands after money typically arrives (payday, start of month), not fifteen minutes later.
• transient_error / processing_error / payment_provider_error — a hiccup between processor, network, or bank. Nothing is wrong with the customer or the card; a prompt retry usually clears it, and there's no reason to email anyone about it.
• transaction_limit_exceeded — the charge tripped a limit on the card. Often clears on a later retry; recurring cases are worth a customer conversation. amount_too_large is a different problem — Shopify defines it as the amount exceeding what the payment method allows, which a retry of the same amount will not change.

Needs the customer, not a retry

• authentication_required / off_session_rejected — the bank wants the customer present to verify (3-D Secure and similar). A retry on its own does not clear it; the customer has to complete verification, so the fix is a link to act on, not silence.

Never recoverable with a retry (hard)

• expired_card / expired_payment_method / invalid_expiry_date — the card on file is past its expiration. Every retry against it is wasted; the card-update email is the only fix, and it should go out on day one. (Expiry dates are visible in advance — this is the one failure you can prevent before it happens. On Shopify Payments, Shopify says card networks can also push a reissued card's details onto the stored method automatically — widely supported in the US, with international support varying — so where that works the failure never occurs.)
• card_declined where the order timeline or gateway detail says the card was reported lost or stolen — Shopify's enum has no distinct code for this, so the signal is in the processor's free-text message, not the code. When you see it, the card will not charge again: card update, immediately.
• invalid_payment_method / payment_method_not_found / buyer_canceled_payment_method — the stored payment method is gone: the customer removed it, or the vaulted record is no longer usable. The subscription needs a fresh payment method to continue.
• incorrect_number / invalid_number / card_number_incorrect — the stored card details themselves are wrong. Re-entry by the customer is the only path.

Ambiguous — the bank won't say (treat carefully)

• do_not_honor — the issuer declined and gave no reason. It's the catch-all: could be balance, could be a risk flag, could be the bank disliking recurring charges that day. Worth one or two well-spaced retries; if it persists, the customer needs to call their bank — no merchant-side setting fixes a bank that won't say why.
• call_issuer — same family, but explicit: the bank wants to hear from the cardholder. Tell the customer that directly; it beats another silent retry.
• generic_error / card_declined with no detail — no signal either way. Treat like a soft decline for a retry or two, then escalate to the card-update path.
• fraud_suspected — a risk system (bank- or Shopify-side) flagged the charge. Don't blindly retry into a fraud flag; repeated attempts make the flag stickier. If the customer is legitimate, this is a support conversation.

Configuration errors — yours, not the customer's

• merchant_account_error / payment_provider_is_not_enabled / merchant_rule — the problem is on the store side: gateway misconfiguration, a disabled provider, or a rule you set. No customer email will fix these; check your payment settings. If a whole day's renewals suddenly fail with the same code, look here first.
• amount_too_small — the renewal was below the gateway's minimum charge, so the card was never asked. Usually a welcome discount that kept applying to every cycle, or line items dropping off until almost nothing was left to bill. No retry and no customer email can fix it — the amount has to change first.
• invoice_already_paid / customer_not_found / customer_invalid — bookkeeping mismatches between the subscription record and the store. Rare, but they masquerade as payment failures while being data problems.

Individual code guides

Each of the codes below has its own deep-dive — what it means, why it happens on renewals specifically, the exact merchant playbook, and whether retrying helps:

• Soft (retryable): insufficient_funds · transient_error · processing_error · transaction_limit_exceeded
• Hard (never retryable): expired_card · invalid_payment_method · incorrect_number · expiry-related family
• Ambiguous (retry with care): do_not_honor · call_issuer · card_declined · payment_method_declined · fraud_suspected · authentication_required · generic_error
• Store-side (fix your setup): amount_too_small · configuration-error family · data-mismatch family

How to actually see these codes

1. Order history: Shopify displays what the bank returned on the declined order — often generic, sometimes specific.
2. Your subscription app: apps differ widely in how much failure detail they surface per renewal. If yours shows only “failed,” the reason still exists underneath — it's just not being shown to you. Our Appstle and Seal guides cover where each app keeps its failure information.
3. The billing API: every failed subscription billing attempt in Shopify carries an error code from the list above — this is where recovery tooling reads the reason and picks a treatment.

The takeaway

You don't need to memorize fifty codes. You need the sort: retry-able, dead-card, ambiguous, or my-configuration — and a different response wired to each. A store that treats insufficient_funds and expired_card the same way is guaranteed to leave money in one of those two buckets, and usually both.

Moorly is an independent product by Velun Labs and is not affiliated with Shopify, Appstle Inc., or Seal Subscriptions. Code names and behavior follow Shopify's public API documentation as of August 2026 and may vary by gateway and plan — always confirm against your own admin.