Shopify Subscription Billing Error Codes: Meaning & How to Fix

Troubleshoot common subscription payment errors and failed billing attempts

1. Introduction

Subscription billing attempts may occasionally fail due to issues with payment methods, banking providers, customer information, inventory availability, or temporary system interruptions. These errors can be found within the Subscription Contract details in TA Subscriptions App, where merchants can manage subscriptions and review billing activity. In some cases, related payment or subscription status information may also be visible to customers through the Customer Portal.

This guide is intended for merchants who want to understand the most common subscription billing errors, what they mean, and how to resolve them. Some issues can be recovered automatically through retry attempts, while others may require action from the customer or updates to store settings.

Use the reference table below to quickly identify an error and its recommended solution. If you still have questions after reviewing this guide, feel free to contact our support team for further assistance.

2. Common Subscription Payment Errors

a. Payment Authentication Errors

These errors occur when additional customer verification is required before a payment can be processed.

Error Code	Meaning	What You Can Do
AUTHENTICATION_ERROR	An error occurred during payment authentication.	Ask the customer to try the payment again and complete any required verification.
AUTHENTICATION_FAILED	Payment authentication failed.	Ask the customer to retry the payment and complete authentication again.
AUTHENTICATION_REQUIRED	Additional authentication is required.	Ask the customer to verify the payment before billing can continue.
EXPIRED_BUYER_ACTION	The required customer action expired.	Ask the customer to complete the payment process again.
OFF_SESSION_REJECTED	Customer approval is required to complete the payment.	Ask the customer to complete payment verification.

b. Card & Payment Method Errors

These errors are related to invalid, expired, unsupported, or missing payment methods.

Error Code	Meaning	What You Can Do
CARD_NUMBER_INCORRECT	The card number is incorrect.	Ask the customer to update their payment details.
INCORRECT_NUMBER	The card number entered is incorrect.	Ask the customer to update their card details.
INVALID_NUMBER	The card number is invalid.	Ask the customer to update their payment details.
EXPIRED_CARD	The customer's card has expired.	Ask the customer to update their card information.
EXPIRED_PAYMENT_METHOD	The saved payment method has expired.	Ask the customer to add a new payment method.
INVALID_EXPIRY_DATE	The card expiry date is invalid.	Ask the customer to update their card information.
INVALID_PAYMENT_METHOD	The payment method is invalid.	Ask the customer to add a new payment method. Please see the methods supported by Shopify here
PAYMENT_METHOD_NOT_FOUND	The saved payment method could not be found.	Ask the customer to add their payment method again.
PAYMENT_METHOD_NOT_SPECIFIED	No payment method is attached to the subscription.	Ask the customer to add a payment method.
PAYMENT_METHOD_UNSUPPORTED	This payment method type is not supported.	Ask the customer to use another payment method. Please see the methods supported by Shopify here.
PURCHASE_TYPE_NOT_SUPPORTED	Subscription payments are not supported by this payment method.	Ask the customer to use another payment method. Please see the methods supported by Shopify here
INVALID_PURCHASE_TYPE	The payment method does not support this purchase type.	Ask the customer to use a different payment method. Please see the methods supported by Shopify here

c. Card Issuer & Bank Declines

These errors are returned by the customer's bank or card issuer.

Error Code	Meaning	What You Can Do
CARD_DECLINED	The card was declined.	Ask the customer to use another card or contact their bank.
PAYMENT_METHOD_DECLINED	The payment method was declined.	Ask the customer to contact their bank or use another payment method. Please see the methods supported by Shopify here
DO_NOT_HONOR	The card issuer declined the transaction.	Ask the customer to contact their bank or use another card.
CALL_ISSUER	The card issuer requires customer verification.	Ask the customer to contact their bank.
RETRY_DECLINED	A retry attempt was declined.	Ask the customer to update their payment method before retrying.
TRANSACTION_LIMIT_EXCEEDED	The transaction exceeds the cardholder's limit.	Ask the customer to contact their bank or use another payment method.
INSUFFICIENT_FUNDS	The customer does not have enough funds.	Ask the customer to add funds or use another payment method, then retry.

d. Customer Information Errors

These errors occur when customer, billing, or shipping information is invalid.

Error Code	Meaning	What You Can Do
CUSTOMER_INVALID	Customer information is invalid.	Confirm that the customer account and subscription are still valid.
CUSTOMER_NOT_FOUND	Customer record could not be found.	Verify that the customer still exists in Shopify.
INVALID_CUSTOMER_BILLING_AGREEMENT	The billing agreement is invalid.	Ask the customer to re-authorize their subscription.
INVALID_BILLING_ADDRESS	The billing address is invalid.	Ask the customer to update their billing information.
INCORRECT_ADDRESS	The billing address does not match payment records.	Ask the customer to update their billing address.
INVALID_SHIPPING_ADDRESS	The shipping address is missing or invalid.	Ask the customer to update their shipping address.
INCORRECT_ZIP	The ZIP/postal code is incorrect.	Ask the customer to update their billing address.

e. Inventory & Product Configuration Errors

These errors occur when products cannot be billed or fulfilled properly.

Error Code	Meaning	What You Can Do
INSUFFICIENT_INVENTORY	Not enough inventory is available.	Restock the product or reschedule the order.
INVENTORY_ALLOCATIONS_NOT_FOUND	No inventory location is available.	Make sure the product is assigned to an active inventory location.
FREE_GIFT_CARD_NOT_ALLOWED	Gift cards must have a value greater than zero.	Remove free gift cards from the subscription configuration.
AMOUNT_TOO_SMALL	The amount is below the minimum charge allowed.	Increase the charge amount before retrying.
AMOUNT_TOO_LARGE	The amount exceeds the limit for this payment method.	Ask the customer to use another payment method or reduce the order value.
INVALID_CURRENCY	The currency is not supported.	Use a supported currency or payment method.

f. Store & Payment Provider Configuration Errors

These errors are caused by store settings, payment gateways, or merchant account configuration.

Error Code	Meaning	What You Can Do
PAYMENT_PROVIDER_IS_NOT_ENABLED	No payment provider is enabled.	Make sure a supported payment provider is active in Shopify. Please see the methods supported by Shopify here
PAYMENT_PROVIDER_ERROR	The payment provider returned an error.	Wait a few hours and try billing again.
PAYMENT_METHOD_INCOMPATIBLE_WITH_GATEWAY_CONFIG	The payment method is incompatible with the current gateway setup.	Check your payment gateway configuration.
MERCHANT_ACCOUNT_ERROR	There is an issue with the merchant account configuration.	Check your payment provider settings in Shopify.
PAYPAL_ERROR_GENERAL	PayPal returned an error.	Check your PayPal account settings and retry later.
TEST_MODE	A live payment was attempted while the gateway is in test mode.	Disable test mode before retrying the charge.
NON_TEST_ORDER_LIMIT_REACHED	The development store order limit has been reached.	Upgrade the store or use a test payment gateway.

g. Fraud, Processing & System Errors

These errors are usually temporary or require manual review.

Error Code	Meaning	What You Can Do
FRAUD_SUSPECTED	The payment was flagged as suspicious.	Review the order before retrying the charge.
MERCHANT_RULE	The transaction was blocked by a merchant rule.	Review any fraud filters or payment restrictions.
CONFIRMATION_REJECTED	Payment confirmation was rejected.	Retry later or ask the customer to try again.
CANCELLED_PAYMENT	The payment was canceled.	Ask the customer to retry the payment.
BUYER_CANCELED_PAYMENT_METHOD	The customer canceled payment authorization.	Ask the customer to authorize the payment method again.
GENERIC_ERROR	An unspecified payment error occurred.	Wait a few hours and try billing again.
PROCESSING_ERROR	The payment provider encountered a processing issue.	Wait a few hours and try billing again.
TRANSIENT_ERROR	A temporary system issue occurred.	Wait a few hours and try billing again.
UNEXPECTED_ERROR	An unexpected error occurred.	Please retry later. If the issue continues, please contact our support team.
INVOICE_ALREADY_PAID	The invoice has already been paid.	Check the billing history before creating another charge.

3. Tips to Reduce Failed Payments

a. Using Features Available in TA Subscriptions App

• Enable Dunning & Retry Logic: Configure automatic payment retries to recover temporary failures such as insufficient funds, declined payments, or temporary gateway issues.

• Send Reminder Emails Before Billing: Enable the Upcoming Order Reminder email to notify customers before their next billing date, helping them prepare funds and avoid missed payments.

• Encourage Customers to Update Payment Methods: Enable the Customer Portal so customers can easily update their payment methods, shipping details, and subscription information when needed.

• Monitor Failed Payments Regularly: Review failed billing attempts and subscription statuses regularly to identify recurring issues and take action before subscriptions are canceled.

b. Best Practices to Share with Your Customers

• Keep Payment Methods Up to Date: Encourage customers to update expired or replaced cards as soon as possible to prevent failed renewals.

• Ensure Sufficient Funds Before Renewal: Remind customers to maintain sufficient funds in their account before upcoming billing dates, especially for high-value subscriptions.

• Verify Billing & Shipping Information: Ask customers to keep their billing and shipping addresses accurate and up to date to avoid renewal and fulfillment issues.

• Use Payment Methods That Support Recurring Billing: Some prepaid, debit, or regional payment methods may not support subscription payments. Encourage customers to use payment methods that allow recurring charges.

• Contact Their Bank if Payments Are Declined: If a payment is repeatedly declined, customers may need to contact their bank to approve recurring subscription transactions or remove spending restrictions.

• Complete Any Required Payment Authentication: Some banks require additional verification for subscription payments. Customers should complete any authentication requests promptly to avoid billing failures.

If you need help, feel free to reach out to us via in-app Live chat, Book a call or at [email protected].