Data-mismatch errors
Codes covered: customer_not_found · customer_invalid · payment_method_not_found · payment_method_not_specified · invoice_already_paid · invalid_customer_billing_agreement · inventory_allocations_not_found · insufficient_inventory
What this error family means
Failures where the subscription's bookkeeping doesn't line up with reality: the contract points at a customer, payment method, billing agreement, or inventory that is missing, invalid, or already settled. They masquerade as payment failures while being data problems.
Why it happens on subscription renewals
- customer_not_found / customer_invalid — the customer record behind the contract was deleted, merged, or is in a state billing can't use.
- payment_method_not_found / payment_method_not_specified — the contract has no usable payment method reference at all (deleted method, or none ever attached after a migration or edit).
- invoice_already_paid — the attempt targets a billing cycle that already settled; usually a duplicate-attempt or out-of-sync retry situation.
- insufficient_inventory / inventory_allocations_not_found — the renewal's line items can't be allocated: product out of stock, variant deleted, or no enabled inventory location.
The merchant playbook
- Don't send customer payment emails for these — the customer's card was never the problem, and 'update your card' for a missing-variant failure is pure confusion.
- Repair the reference: reattach a payment method, restore or relink the customer, fix the stocked-out or deleted product. The failure clears when the data does.
- For invoice_already_paid, verify the cycle actually settled (order exists, payment captured) and then stand down — the money is already in; the failure is an artifact.
- Audit for clusters after migrations, app switches, or bulk product edits — these codes appearing in groups date-stamped to a change are the change's fingerprints.
Should you retry?
Not until the underlying record is repaired — after that, the next scheduled attempt usually just works. Inventory members recover on their own when stock returns, but a deleted variant needs a contract edit.
Common questions
Why would a subscription point at a customer that doesn't exist?
Deletions and merges. A customer record removed or consolidated after the contract was created leaves the contract holding a dead reference — nothing looked broken until the next billing attempt tried to use it.
Are inventory failures really 'payment' failures?
They surface in the same failed-billing stream, but no charge was declined — the renewal couldn't even assemble its order. That's why classifying failure codes matters: the fix lives in your catalog, not in dunning.
Related codes: invalid_payment_method · generic_error · merchant_account_error · or see the
full decline-code guide.
Where Moorly fits: Moorly reads the decline reason behind every failed renewal in your existing subscription app and applies the playbook above automatically — the right treatment per code, with a dollar figure on what each failure family costs your store. It starts read-only. Join the early-access list →
Moorly is an independent product by Velun Labs and is not affiliated with Shopify, Appstle Inc., or Seal Subscriptions s.r.o. Code names follow Shopify's public API documentation as of August 2026; bank behavior varies by issuer — always confirm against your own admin.