Guide
How Shopify subscriptions work: selling plans, contracts and billing attempts
A selling plan sets how a product can be bought on repeat. A subscription contract is the agreement between the customer and the merchant. Each charge is a billing attempt on that contract, and it can succeed or fail. A failed attempt is a payment event on the same contract.
By MergeGuard team
3 min read
On this page
Key insight
The contract and the billing attempt are separate things. A failed charge is a payment event, and the customer may not have decided anything yet.
4 words used here
Selling plans
Shopify’s developer documentation describes two types of selling plan. They differ in when you ask for money.
The last two rows are our reasoning from the two definitions, and Shopify’s pages don’t put it that way.
Subscription contracts
A subscription contract is, in Shopify’s words, “the agreement between a customer and a merchant over a specific term for recurring purchases” (Subscriptions). The developer documentation says contracts “might have a status of active, paused, or failed”.
The contract is attached to a customer profile. That detail matters later: when the same person has two profiles, the contract sits on only one of them.
It also explains a merge limit, because Shopify refuses to merge a profile that has, or has ever had, a subscription contract (in plain words: the record of a customer’s subscription). The details are in duplicate profiles and subscription contracts.
MergeGuard’s Subscription lists read a subscriber’s orders across all their profiles, so a second profile no longer hides the signs. Every plan, Free included, sees each list’s count, and the people appear on a plan that includes the Subscription lists (subscribers who may cancel).
Billing attempts
An app collects payment on a contract. Shopify’s documentation says “apps charge customers for their subscriptions by initiating a billing attempt on the subscription contract”.
When an attempt fails, Shopify sends a webhook (a message to the app) described as “Occurs when a billing attempt fails”. The documentation’s example error reads “Payment method was declined by processor” (Subscription contracts).
The failed branch explains why a failed payment can pass without a trace in your order list. The attempt failed, so there may be no order to look at. A failed attempt is a payment event, so it does not show by itself that the customer chose to leave.
What customers can do
Shopify’s help page for its Subscriptions app says: “Customers can resume, skip, or cancel their subscriptions, and they can manage their payment methods and shipping address” (Shopify Subscriptions app).
So a subscriber has several quiet ways to change what they receive. A skipped delivery, a canceled subscription and an expired card are different events, and each leaves a different mark in your data.
Where it goes wrong
Two things can go wrong, and each has its own guide.
- A payment fails. Shopify lets the merchant adjust the retries and choose a final action. Read failed payments on Shopify subscriptions.
- A subscriber has a second account. The subscription profile shows the subscription orders, and another profile may hold the one-time orders. Read subscribers who buy outside their subscription.
Worked example (made up)
150 subscribers → 14 with a second account → 6 showing signsTake the self-check below to see which gap to close first.
Optional self-check (4 questions)
Four questions about your own practice. Each answer is worth 0, 1 or 2 points. Your answers stay in your browser. We record only the guide and your result band.
Add up the points beside your answers (the highest total is 8) and find your total in the list below.
Answer every question to see your result.
0 to 2: Start with the terms
Selling plan, contract and billing attempt describe every charge you collect. Read the contract entry first, then the failed payments guide.
3 to 5: Review your retry settings
You know the outline. Write down your retry values and your final action, then read what each setting does.
6 to 8: Add a second-account check
Your billing basics are in place. The next gap is subscribers whose other orders sit on another profile.
See how to find subscribers who buy outside their plan See what the first scan shows
Question about this chapter? Email support@mergeguard.store.
Keep reading (13 links: 1 Guide, 1 Explainer, 1 Playbook, 1 Help, 1 Term, 2 Features, 1 Page, 5 Sources)
Related
- PlaybookSubscribers who buy outside their subscription
- ExplainerDuplicate customers and subscriptions: why a subscriber’s second account matters
- TermSubscription contract
- FeatureAudiences
- PageWhy can’t I merge customers in Shopify?
- HelpBuild an audience list that counts each person once
- GuideAll of Subscriptions
Sources
- Shopify developer docs: Subscriptions (selling plans and subscription contracts)
- Shopify developer docs: Subscription contracts (billing attempts and failed billing)
- Shopify Help Center: Shopify Subscriptions app (what customers can do)
- Shopify Help Center: Managing Shopify Subscriptions (billing attempts)
- Shopify Help Center: Managing customers, Limitations for merging customer profiles
0 of 4 readSaved in this browser only.
