> For the complete documentation index, see [llms.txt](https://ta-subscriptions-app.easto.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ta-subscriptions-app.easto.io/resources/help-center/troubleshooting-guide.md). # Shopify Subscription Billing Error Codes: Meaning & How to Fix ### 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](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) | | `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](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations). | | `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](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) | | `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](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) | #### 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](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) | | `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](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) | | `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***](https://go.crisp.chat/chat/embed/?website_id=c4ae10a3-f762-4968-b35a-c931caf62a96)***,*** [***Book a call***](https://calendly.com/ta-subscription-app-support/30min) *or at* [***support@tech-arms.io***](mailto:support@tech-arms.io)***.*** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ta-subscriptions-app.easto.io/resources/help-center/troubleshooting-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.