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
You can see common Shopify error codes for failed subscription billing attempts from SubscriptionBillingAttemptErrorCode.
For more details, read our guide “What do billing attempt errors messages mean, and how do I resolve them?”.
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. - If migrating between payment providers, such as from Stripe to Shopify Payments, use this method to request customers update their payment details to the new provider. This ensures continuity of subscription renewals during the transition.
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. It is also crucial during transitions between payment gateways, where all customers need to re-authorize new billing agreements to maintain uninterrupted service.
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.