Understanding Subi and Shopify’s Roles in Subscription Billing
When a customer subscribes to your product, Subi manages the subscription contract and sends billing attempts to Shopify.
Shopify handles all payment processing—both the initial charge and all renewals. Subi does not process payments directly.
Subi’s responsibility: Creates and schedules billing attempts for each subscription, sends them to Shopify for processing, and shows you the status and error messages from Shopify.
Shopify’s responsibility: Processes the payment using the customer’s saved method and returns the result to Subi (successful or failed).
Because Shopify manages the payment process, all technical payment failure details come from Shopify’s systems and your chosen payment processor.
Why Do Subscription Payments Fail?
A subscription contract is an agreement for recurring purchases over a set or ongoing period. Each renewal triggers a billing attempt, where Subi sends the payment request to Shopify.
Successful billing attempt: Shopify processes payment and creates an order with status Paid.
Failed billing attempt: Shopify returns a failure status along with an error code and error message.
Since Shopify is the payment processor, Subi can only display the information Shopify provides—no additional details are available from Subi.
Common Payment Failure Reasons and Actions to Take
Here are common Shopify error codes from failed subscription billing attempts and how you can respond as a merchant:
Error Code | Meaning | Action to Take |
AMOUNT_TOO_SMALL | The amount is too small to process (e.g., billing under Shopify’s minimum). | Ask customer to verify total; review any $0 or minimal charge scenarios. |
AUTHENTICATION_ERROR | An error occurred during payment authentication (e.g., 3D Secure step). | Ask customer to complete any required authentication or retry with another method. |
BUYER_CANCELED_PAYMENT_METHOD | Payment method was canceled by the buyer. | Prompt customer to add a new payment method and retry. |
CARD_NUMBER_INCORRECT | The card number entered is invalid. | Ask customer to confirm and re-enter card details. |
CUSTOMER_INVALID or CUSTOMER_NOT_FOUND | The customer record is invalid or missing. | Check customer account setup; ensure correct customer association and retry. |
EXPIRED_PAYMENT_METHOD | The saved payment method has expired. | Prompt customer to update their card with a current expiration date. |
FRAUD_SUSPECTED | Shopify flagged the attempt for suspected fraud. | Advise customer to try another payment method or contact support. |
FREE_GIFT_CARD_NOT_ALLOWED | A free gift card (value $0) is not eligible for subscription billing. | Remove free gift card from subscription or adjust billing amount. |
INSUFFICIENT_FUNDS | The customer's card lacks sufficient funds. | Ask customer to add funds or use a different payment method. |
INSUFFICIENT_INVENTORY | Not enough inventory to fulfill the subscription. | Review stock levels or inventory rules before retrying. |
INVALID_CUSTOMER_BILLING_AGREEMENT | The billing agreement ID is invalid. | Verify and update the customer’s payment agreement. |
INVALID_PAYMENT_METHOD | The method is invalid or no longer supported. | Ask the customer to add a new valid payment method. |
INVALID_SHIPPING_ADDRESS | Address is missing or invalid. | Request customer verify or update their shipping details. |
The zip code you supplied failed validation | This error means the ZIP code entered at checkout does not match the one on file with the customer’s credit card company. If you have enabled the Shopify Payments setting to decline charges when ZIP code verification fails, any mismatch will cause the payment to be declined. | Contact the customer and ask them to confirm the ZIP code registered with their card issuer. Have them update their billing address in their account or with their bank, then retry the payment. If appropriate for your business, you can disable strict ZIP code verification in Shopify:
|
INVENTORY_ALLOCATIONS_NOT_FOUND | No valid location identified for inventory. | Ensure inventory locations are properly assigned for order fulfillment. |
INVOICE_ALREADY_PAID | Payment has already been processed for this invoice. | Confirm duplicate billing not occurring; no action needed. |
NON_TEST_ORDER_LIMIT_REACHED | Live payment limits reached; requires test gateway. | Use a test gateway for further billing attempts, or wait/reset limits. |
PAYMENT_METHOD_DECLINED | The payment method was declined by processor. | Prompt customer to update or replace their card. |
PAYMENT_METHOD_INCOMPATIBLE_WITH_GATEWAY_CONFIG | Payment method incompatible with gateway settings. | Ask customer to use a supported card type or change gateway config. |
PAYMENT_METHOD_NOT_FOUND | The saved payment method cannot be located. | Have customer re-add a valid payment method. |
PAYMENT_PROVIDER_IS_NOT_ENABLED | Payment provider is disabled in store settings. | Enable the appropriate payment gateway in Shopify settings. |
PAYPAL_ERROR_GENERAL | A general PayPal-related error occurred. | Have customer try an alternate payment method or contact PayPal. |
PURCHASE_TYPE_NOT_SUPPORTED | This type of transaction (e.g., purchase type) is unsupported. | Ask customer to use a supported payment type or adjust settings. |
TEST_MODE | Attempted a live charge while gateway is in test mode. | Switch gateway to live mode or use test card appropriately. |
TRANSIENT_ERROR | A temporary error occurred (e.g., network or gateway downtime). | Retry billing later or after a short delay. |
UNEXPECTED_ERROR | An unknown or unexpected error occurred. | Retry the charge or investigate with support if it persists. |
If the error message is unclear (e.g., “Your card was declined”), contact your payment processor’s support:
How Customers Can Update Their Payment Method
Customers can update their payment method through their Customer Portal or via a secure link you send them.
To send an update link for a single subscription:
In Subi, go to Contracts.
Open the subscription contract for the customer (you can find it by searching the Subscription ID from the failed payment notification email).
In the Payment method section, click Send link to update card.
Shopify will email the customer a secure link to update their card. Once updated, Subi will use the new method for the next billing attempt.
To send update links in bulk:
From the Failed Payment tab in your Subscription contracts list, select multiple subscriptions with the same failure reason (e.g., “Payment method was revoked” or “Your card has expired”).
Click Bulk actions → Send update payment method link.
This will send the update card email to all selected customers at once, allowing you to quickly address common payment failures across multiple subscriptions.
This is especially useful when you notice repeated failure reasons in your list, such as expired cards or revoked payment methods, so you can resolve multiple cases in a single step.
How You’re Notified of Failed Payments
Enable failed payment notifications in Subi settings to notify both you and your customer.
You can:
Receive email alerts when payments fail.
View failed payments in Subi: Contracts tab → Failed Payment segment.
Open a specific subscription contract, in the Billing History section, hover over the “Payment fail” tag for any billing attempt to see the reason.
Retrying Failed Subscriptions
To reduce failed payments:
Enable Billing Management in Subi.
Set retry intervals for failed charges.
Ensure both merchant and customer notifications are on.
When enabled, Subi will retry the payment automatically according to your retry settings after the failure cause is addressed.
Viewing Billing Attempt Retrials
If a billing attempt fails and Subi retries it, you can view all retrials by clicking the three dots next to that billing attempt in the Billing History table of the subscription contract. This opens a detailed view showing the original attempt, all retrials, and their respective statuses and timestamps.
Next Steps:
Review Shopify’s payment error documentation for more detail.
Ensure failed payment notifications are active in Subi.
Use the “Send link to update card” feature to quickly help customers resolve issues.