When do payment and billing errors happen?
Payment and billing errors occur when a subscription charge fails during automated billing. Skio surfaces the exact error code and message returned by Shopify or your payment gateway.
Skio doesn't process payments directly, so these errors originate from your payment provider.
The error code is a broad category, while the error message is a more specific description from the processor. A single error code can map to multiple error messages.
Where payment errors appear
In your Skio Dashboard > Subscription Management
In the lefthand menu of your Skio Dashboard, go to Subscribers, then click Subscriptions.
Search for the subscription with the failed charge, or click on the Failed tab to see all failed payments.
The error will appear on the Subscription card under Last Status Change and in the Subscription audit log when you click on View subscription history.
View error messages from the Subscription card.
Each failed billing attempt displays the error code and message from your payment gateway. After resolving the underlying issue, you can retry the charge by clicking Get now.
For your customers
Customers may encounter payment errors in several places:
Customer Portal: When adding or updating payment methods (common with Shop Pay errors or invalid billing details)
Bank or app notifications: Declines for insufficient funds, expired cards, or "do not honor" responses
Email notifications: If you've set up failure notifications through Klaviyo, customers receive alerts when Shopify returns a failed charge
List of all payment errors
Shopify error codes
These are the error codes returned by Shopify's billing API when a subscription payment fails. See Shopify's full list of errors here.
The "Error Message in Skio" column shows what appears in your Skio Dashboard's subscription activity log. Customers do not see this message anywhere in the Customer Portal, and Skio's default failure notifications don't include it either — only card brand, last 4 digits, and expiration are shown to customers by default.
Error Code | Error Message in Skio | Steps to resolve |
|---|---|---|
| "Amount too large" | Reduce order value or check maximum charge limits for the payment method |
| "The amount is too small" | Increase order value or check minimum charge requirements (amount must convert to at least 50 cents) |
| "There was an error during the authentication" | Customer needs to complete 3DS verification |
| "Authentication failed" | Treated as a generic decline, not routed through the 3DS challenge flow. Customer should retry payment with a different card if the issue persists. |
| "Authentication required" | Treated as a generic decline, not routed through the 3DS challenge flow. Customer should retry payment with a different card if the issue persists. |
| "Payment method was canceled by buyer" | Customer must add a new payment method |
| "Card issuer needs to be contacted" | Customer should contact their card issuer directly |
| "Payment canceled" | No action needed - check for duplicate or intentionally canceled attempt |
| "Card declined" | Customer should contact bank or use a different card and then retry payment |
| "Card number was incorrect" | Customer should re-enter card details |
| "Payment confirmation rejected" | Customer needs to retry the confirmation step |
| "Customer is invalid" or "Customer does not have email or phone" | Verify customer account in Shopify and ensure they have a proper email address or phone number |
| "Customer was not found" | Customer account may have been deleted |
| "Declined by card issuer" | Customer should contact their bank |
| "Customer action expired" | Treated as a generic decline, not routed through the 3DS challenge flow. Customer should retry the action, then retry payment if needed. |
| "The card has expired" | Customer needs to update card expiration date |
| "Payment method is expired" | Customer needs to update card expiration date |
| "Fraud was suspected" | Customer should contact their bank |
| "Gift card not allowed" | Merchant should check gift card / free product configuration |
| "Payment error" | Contact support if persists |
| "Incorrect billing address" | Customer should update billing address |
| "Incorrect card number" | Customer should re-enter card details |
| "Incorrect ZIP/postal code" | Ensure the zip code is correct |
| "Insufficient funds" | Customer should use a different payment method |
| "Not enough inventory found" | Check product stock levels |
| "Invalid billing address" | Customer should update billing address |
| "Unsupported currency" | Merchant should check payment provider currency support settings |
| "Billing agreement/transaction ID is invalid" | Customer needs to re-authorize payment method |
| "Invalid card expiry date" | Customer should re-enter card expiration date |
| "Invalid card number" | Customer should re-enter card details |
| "Payment method is invalid" or "Unable to generate vaulted remote token payment method" | Customer should update or add new payment method |
| "Invalid purchase type" | Card doesn't support subscription payments |
| "Shipping address is missing or invalid" | Customer must update shipping address |
| "No inventory location found or enabled" | Check fulfillment locations in Shopify |
| "A payment has already been made for this invoice" | No action needed - likely duplicate attempt |
| "Merchant account error" | Merchant should check payment provider account settings |
| "Blocked by merchant rule" | Merchant should review fraud/decline rules configured in their payment provider |
| "Non-test order limit reached" | Use a test payment gateway to place another order |
| "Off-session payment rejected" | Customer needs to complete the payment directly (action required) |
| "Payment method was declined by processor" or "Your card was declined" | Customer should contact bank or use different card and then retry payment |
| "Payment method incompatible with gateway" | Merchant config issue - dev vs prod mismatch |
| "Payment method was not found" or "Payment method was revoked" | Customer needs to add a payment method. This also commonly occurs when a customer removes the card from Shop Pay, breaking the billing agreement. Customer must add a new payment method and then retry. |
| "No payment method on file" | Customer needs to add a payment method |
| "Unsupported payment method" | Customer should use a supported payment method |
| "Payment provider error" | Contact support if persists |
| "Payment provider is not enabled" | Merchant must enable payment provider in Shopify |
| "PayPal Error General" | Customer should check PayPal account |
| "Processing error" | Auto-retry or contact support if persists |
| "Purchase type is not supported" or "Your card does not support this type of purchase" | Card doesn't support subscription payments |
| "Retry declined" | Customer should contact bank or use a different card |
| "Gateway in test mode with live card" | Merchant config issue - dev vs prod mismatch |
| "Transaction limit exceeded" | Customer should contact their bank to increase the limit, or use a different card |
| "Transient error, try again later" | Auto-retry or manual retry later |
| "Unexpected error during billing attempt" | Contact support if persists |
Skio-specific error messages
Context | Error Message in Skio | Steps to resolve |
|---|---|---|
Rate Limiting |
| Customer hitting daily purchase limits. Adjust daily limit settings under Settings > General > Max daily orders per subscription. |
Fraud Review |
|
|
Generic Failure |
| Billing attempt failed (with |
Out of Stock |
| Out of Stock (OOS) check before billing. Swap with an item that is in stock, or wait for original item to be restocked and then retry payment. |
3DS Pending |
|
|
Credit card specific errors
Error | Error Message in Skio | Steps to resolve |
|---|---|---|
| "has already been taken" | Use a different credit card. |
| "Your card was declined. Your request was in test mode..." | Must use a test card number while in test mode. |
| "The card was declined" | Must be resolved on the customer’s side with their credit card company. |
| "verification value is incorrect" | Ensure the verification value is correct. |
| "zip code is incorrect" | Ensure the zip code is correct. |
Stripe error codes
Common codes from Stripe that map to Shopify errors.
Stripe Code | Maps to | Meaning |
|---|---|---|
|
| Card lacks funds, must be resolved by customer. |
|
| Unknown/blocked, reach out to Stripe support. |
|
| Card is expired, must be resolved by customer. |
|
| Wrong CVC code, ensure accurate CVC value is filled in. |
|
| General decline. |
|
| Suspected fraud. |
|
| Card reported stolen/lost, must be resolved by customer. |
|
| Needs 3DS verification, must be resolved by customer. |
FAQ
My customer can’t take X action from their customer portal, or the action is missing
Make sure the ability to take the action is turned on in your Customer Portal settings.
For Customer Portal v3 (CPv3), see our guide here.
For Customer Portal v2 (CPv2), see your guide here.
When will the payment retry after a customer resolves the error?
The payment will retry according to your dunning settings, or the customer and your team can use the Get now button to retry the payment immediately, as long as the setting is toggled on for your customers in your Customer Portal settings.
For Customer Portal v3 (CPv3), see our guide here.
For Customer Portal v2 (CPv2), see your guide here.
What happens if some or all items in a subscription are out of stock at billing time?
If all items are out of stock, billing is skipped entirely. No charge is made, no failure email is sent, and the subscription won't appear in the Failed tab.
If only some items are out of stock, the out of stock line items are removed before billing and charges for the remaining items. The order goes through successfully but at a lower amount than expected.
In both cases, you can confirm what happened by opening the subscription, clicking View subscription history, and looking for a "Billing out of stock" event. It will show exactly which products were affected. Once items are back in stock, use the Get now button to retry billing, or re-add the removed lines to the subscription manually.
What does the Shopify error "PAYMENT_PROVIDER_IS_NOT_ENABLED" mean, and how do I resolve it?
This error means the payment provider processing the charge (Shopify Payments, PayPal, or another gateway) isn't fully enabled or configured in Shopify. It's a provider-side issue, so it needs to be resolved in Shopify's payment settings rather than in Skio.
Common causes:
The payment provider isn't enabled or fully configured in Shopify's payment settings.
Recurring billing isn't turned on for that provider. This is common with PayPal's automatic payments feature.
The provider was disabled, removed, or had its credentials changed without being reconnected.
The customer's saved payment method is no longer valid or authorized.
How to resolve it:
In Shopify Admin, go to Settings > Payments and confirm the provider is enabled and fully configured. For PayPal, make sure recurring billing is turned on in the PayPal account settings.
If the provider is configured correctly, ask the customer to update their payment method in the Customer Portal, or reconnect PayPal to refresh the authorization.
Once the provider and payment method are confirmed, retry the charge using Get now on the Subscription card in your Skio Dashboard.