> For the complete documentation index, see [llms.txt](https://subscriptions-docs.tech-arms.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://subscriptions-docs.tech-arms.io/resources/help-center/troubleshooting-guide.md).

# Shopify Subscription Billing Error Codes: Meaning & How to Fix

What each subscription payment error code means, where to find it in the app, and how to fix it.

When a subscription payment fails, Shopify returns an **error code** that explains why. TA Subscriptions App shows this code on the subscription so you can see what went wrong and what to do next.

Most failures come from the customer's card or bank. Some are temporary and fix themselves when the app retries. Others need the customer to update their payment details, or need you to change a store setting.

## Find the error code

{% stepper %}
{% step %}

### Open the subscription

In the app menu, click **Subscriptions** and open the subscription. Its status shows **Failed** after a failed payment.
{% endstep %}

{% step %}

### Check Past orders

Click the **Past orders** tab. Each billing cycle lists its payment attempts. For a failed attempt, the **Payment status** column shows the error code, such as **INSUFFICIENT\_FUNDS**.

Hover over the code to see Shopify's message. Click **View help** to open this guide in the app's help chat.

![The Past orders tab with a failed payment attempt and the error code popover highlighted](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FhurS4zcyNjAtUOKFnoGT%2Fpast-orders-payment-error.png?alt=media)
{% endstep %}

{% step %}

### Fix the cause and charge again

Look up the code in the tables below and follow **What to do**. Then charge the cycle again with **Recharge Cycle**, or wait for the next automatic retry. See [Past orders](https://subscriptions-docs.tech-arms.io/features/subscriptions/past-orders.md).
{% endstep %}
{% endstepper %}

## What happens after a failed payment

* The subscription status changes to **Failed**. No order is created for that cycle.
* By default, the customer gets the **Payment failed (retrying)** email and you get the **Payment failed** email.
* The app retries the payment according to your [Renewal & Dunning](https://subscriptions-docs.tech-arms.io/features/email-notifications/renewal-and-dunning-settings.md) settings. After the last retry, the customer gets the **Payment failed (last attempt)** email.
* The app does not pause or cancel the subscription. The next cycle is still charged on its date.
* When a later payment succeeds, the subscription returns to **Active**.

## Common fixes

| Fix                                       | How                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ask the customer to update their card** | Open the subscription and click the pencil icon next to **Payment method**. In **Change payment method**, click **Send link to update card**. Shopify emails the customer a secure link. Customers can also do this in the [Customer Portal](https://subscriptions-docs.tech-arms.io/features/customer-portal.md), under **Payment method**. |
| **Switch to another saved card**          | In **Change payment method**, click **Select** next to another card the customer has saved.                                                                                                                                                                                                                                                  |
| **Charge again**                          | In **Past orders**, click **…** on the billing cycle and choose **Recharge Cycle**.                                                                                                                                                                                                                                                          |
| **Wait for the retry**                    | For temporary errors, the next automatic retry often succeeds.                                                                                                                                                                                                                                                                               |

## Error codes

### Payment authentication

The customer's bank wants the customer to confirm the payment, for example with 3D Secure.

| Error code                | Meaning                                                      | What to do                                                                                         |
| ------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `AUTHENTICATION_ERROR`    | An error occurred while authenticating the payment.          | Ask the customer to update their payment method and complete any verification their bank asks for. |
| `AUTHENTICATION_FAILED`   | Authentication failed.                                       | Same as above.                                                                                     |
| `AUTHENTICATION_REQUIRED` | The bank needs extra authentication.                         | Same as above.                                                                                     |
| `EXPIRED_BUYER_ACTION`    | The customer didn't complete a required step in time.        | Ask the customer to update their payment method, then charge again.                                |
| `OFF_SESSION_REJECTED`    | The bank refused a charge made without the customer present. | Ask the customer to update their payment method or contact their bank to allow recurring charges.  |

### Card and payment method

The saved card or payment method is wrong, expired, missing, or can't be used for subscriptions.

| Error code                     | Meaning                                                  | What to do                                                                                                                                                                                                |
| ------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CARD_NUMBER_INCORRECT`        | The card number is incorrect.                            | Ask the customer to update their card.                                                                                                                                                                    |
| `INCORRECT_NUMBER`             | The card number is incorrect.                            | Ask the customer to update their card.                                                                                                                                                                    |
| `INVALID_NUMBER`               | The card number is invalid.                              | Ask the customer to update their card.                                                                                                                                                                    |
| `INCORRECT_CVC`                | The security code is incorrect.                          | Ask the customer to update their card.                                                                                                                                                                    |
| `INVALID_CVC`                  | The security code is invalid.                            | Ask the customer to update their card.                                                                                                                                                                    |
| `INCORRECT_PIN`                | The PIN is incorrect.                                    | Ask the customer to update their card or use another one.                                                                                                                                                 |
| `EXPIRED_CARD`                 | The card has expired.                                    | Ask the customer to update their card.                                                                                                                                                                    |
| `EXPIRED_PAYMENT_METHOD`       | The saved payment method has expired.                    | Ask the customer to add a new payment method.                                                                                                                                                             |
| `INVALID_EXPIRY_DATE`          | The card's expiry date is invalid.                       | Ask the customer to update their card.                                                                                                                                                                    |
| `INVALID_PAYMENT_METHOD`       | The payment method is invalid.                           | Ask the customer to add a new payment method.                                                                                                                                                             |
| `PAYMENT_METHOD_NOT_FOUND`     | The saved payment method no longer exists.               | Ask the customer to add a payment method again.                                                                                                                                                           |
| `PAYMENT_METHOD_NOT_SPECIFIED` | The subscription has no payment method.                  | Ask the customer to add a payment method.                                                                                                                                                                 |
| `PAYMENT_METHOD_UNSUPPORTED`   | This type of payment method isn't supported.             | Ask the customer to use a card or another supported method. See [eligibility](https://subscriptions-docs.tech-arms.io/getting-started/must-read-shopify-subscriptions-app-eligibility-considerations.md). |
| `PURCHASE_TYPE_NOT_SUPPORTED`  | This payment method can't be used for subscriptions.     | Same as above.                                                                                                                                                                                            |
| `INVALID_PURCHASE_TYPE`        | This payment method doesn't allow this type of purchase. | Same as above.                                                                                                                                                                                            |

### Bank and card issuer declines

The customer's bank refused the payment.

| Error code                   | Meaning                                    | What to do                                                                     |
| ---------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
| `CARD_DECLINED`              | The card was declined.                     | Ask the customer to contact their bank or use another card.                    |
| `PAYMENT_METHOD_DECLINED`    | The payment method was declined.           | Ask the customer to contact their bank or use another payment method.          |
| `DO_NOT_HONOR`               | The bank declined without giving a reason. | Ask the customer to contact their bank or use another card.                    |
| `CALL_ISSUER`                | The bank wants the customer to call them.  | Ask the customer to call their bank, then charge again.                        |
| `INSUFFICIENT_FUNDS`         | Not enough money in the account.           | Wait for the next retry, or ask the customer to add funds or use another card. |
| `TRANSACTION_LIMIT_EXCEEDED` | The charge is over the card's limit.       | Ask the customer to contact their bank or use another card.                    |
| `RETRY_DECLINED`             | A retry was declined.                      | Ask the customer to update their payment method before you charge again.       |

### Customer and address

| Error code                           | Meaning                                                           | What to do                                                                                     |
| ------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `CUSTOMER_INVALID`                   | The customer record is invalid.                                   | Check the customer in Shopify admin.                                                           |
| `CUSTOMER_NOT_FOUND`                 | The customer no longer exists in Shopify.                         | Check whether the customer was deleted. If so, cancel the subscription.                        |
| `INVALID_CUSTOMER_BILLING_AGREEMENT` | The saved billing agreement, for example with PayPal, is invalid. | Ask the customer to update their payment method.                                               |
| `INVALID_BILLING_ADDRESS`            | The billing address is invalid.                                   | Ask the customer to update their payment details.                                              |
| `INCORRECT_ADDRESS`                  | The billing address doesn't match the card.                       | Same as above.                                                                                 |
| `INCORRECT_ZIP`                      | The ZIP or postal code doesn't match the card.                    | Same as above.                                                                                 |
| `INVALID_SHIPPING_ADDRESS`           | The shipping address is missing or invalid.                       | Edit the address on the subscription, or ask the customer to update it in the Customer Portal. |

### Inventory and order amount

| Error code                        | Meaning                                              | What to do                                                                                                                                                                                                                                       |
| --------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `INSUFFICIENT_INVENTORY`          | A product is out of stock.                           | Restock the product, then charge again. To charge renewals even when stock runs out, turn on **Allow Overselling** in [Renewal & Dunning](https://subscriptions-docs.tech-arms.io/features/email-notifications/renewal-and-dunning-settings.md). |
| `INVENTORY_ALLOCATIONS_NOT_FOUND` | No active location stocks the product.               | Make sure the product is stocked at an active location in Shopify.                                                                                                                                                                               |
| `FREE_GIFT_CARD_NOT_ALLOWED`      | A gift card in the order has a price of zero.        | Remove the free gift card from the subscription, or give it a price.                                                                                                                                                                             |
| `AMOUNT_TOO_SMALL`                | The order total is below the minimum charge.         | Check the subscription's prices and discounts.                                                                                                                                                                                                   |
| `AMOUNT_TOO_LARGE`                | The order total is over this payment method's limit. | Ask the customer to use another payment method.                                                                                                                                                                                                  |
| `INVALID_AMOUNT`                  | The amount isn't valid for this payment method.      | Check the subscription's prices and discounts, or ask the customer to use another payment method.                                                                                                                                                |
| `INVALID_CURRENCY`                | The payment method doesn't support this currency.    | Ask the customer to use another payment method.                                                                                                                                                                                                  |

### Store and payment provider settings

These errors come from your store's payment setup, not from the customer.

| Error code                                        | Meaning                                                                                                          | What to do                                                                                                                                                                                     |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PAYMENT_PROVIDER_IS_NOT_ENABLED`                 | The payment provider isn't active.                                                                               | Turn on a supported payment provider in Shopify. See [eligibility](https://subscriptions-docs.tech-arms.io/getting-started/must-read-shopify-subscriptions-app-eligibility-considerations.md). |
| `PAYMENT_PROVIDER_ERROR`                          | The payment provider had a problem.                                                                              | Wait for the next retry. If it continues, contact your payment provider.                                                                                                                       |
| `MERCHANT_ACCOUNT_ERROR`                          | Your payment account isn't set up correctly.                                                                     | Check your payment provider settings in Shopify.                                                                                                                                               |
| `PAYPAL_ERROR_GENERAL`                            | PayPal returned an error.                                                                                        | Check your PayPal account, then charge again.                                                                                                                                                  |
| `TEST_MODE`                                       | Your payment provider is in test mode, but the saved card is real.                                               | Turn off test mode, then charge again.                                                                                                                                                         |
| `PAYMENT_METHOD_INCOMPATIBLE_WITH_GATEWAY_CONFIG` | The payment method doesn't match your test mode setting, for example a test card after you turned test mode off. | Cancel test subscriptions, or turn test mode back on to test.                                                                                                                                  |
| `NON_TEST_ORDER_LIMIT_REACHED`                    | Your development store reached its limit of real orders.                                                         | Use a test payment method.                                                                                                                                                                     |

### Fraud, processing, and other errors

| Error code                      | Meaning                                                      | What to do                                                                   |
| ------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `FRAUD_SUSPECTED`               | The payment looks fraudulent.                                | Review the customer and earlier orders before you charge again.              |
| `MERCHANT_RULE`                 | A rule you set, such as a fraud filter, blocked the payment. | Review your fraud filters and payment rules.                                 |
| `CONFIRMATION_REJECTED`         | The payment confirmation was rejected.                       | Wait for the next retry, or ask the customer to update their payment method. |
| `CANCELLED_PAYMENT`             | The payment was cancelled.                                   | Ask the customer to update their payment method, then charge again.          |
| `BUYER_CANCELED_PAYMENT_METHOD` | The customer cancelled the payment authorization.            | Ask the customer to authorize the payment method again.                      |
| `INVOICE_ALREADY_PAID`          | This cycle is already paid.                                  | Check **Past orders** before you charge again.                               |
| `INVALID_REQUEST`               | The payment request was invalid.                             | Wait for the next retry. If it continues, contact us.                        |
| `GENERIC_ERROR`                 | An unspecified payment error.                                | Wait a few hours and charge again.                                           |
| `PROCESSING_ERROR`              | The payment provider couldn't process the payment.           | Wait a few hours and charge again.                                           |
| `TRANSIENT_ERROR`               | A temporary error.                                           | Wait for the next retry.                                                     |
| `UNEXPECTED_ERROR`              | An unexpected error.                                         | Wait and charge again. If it continues, contact us.                          |

## Reduce failed payments

* **Keep retries on.** Set retries in [Renewal & Dunning](https://subscriptions-docs.tech-arms.io/features/email-notifications/renewal-and-dunning-settings.md). Many temporary declines succeed on a later try.
* **Remind customers before billing.** Turn on the **Upcoming Order Reminder Email** in [Email Notifications](https://subscriptions-docs.tech-arms.io/features/email-notifications/email-notifications.md) so customers can update their card in time. This email is available on some plans only.
* **Let customers fix their own details.** Share the [Customer Portal](https://subscriptions-docs.tech-arms.io/features/customer-portal.md) link, where customers can update their payment method and address.
* **Check failed subscriptions often.** In **Subscriptions**, look for subscriptions with the **Failed** status.

Tips to share with customers:

* Update expired or replaced cards before the next billing date.
* Use a payment method that allows recurring charges.
* Complete any verification the bank asks for.
* Contact the bank if payments keep getting declined.

## Good to know

* Error codes and their messages come from Shopify and the payment provider. The app shows them as they are.
* Codes appear only on payment attempts that failed. A paid attempt shows the order number and **Paid**.
* **Recharge Cycle** charges the order even if a product is out of stock.

*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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://subscriptions-docs.tech-arms.io/resources/help-center/troubleshooting-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
