How Shopify subscriptions work: selling plans, contracts and billing attempts

A subscription looks like one thing to a customer and three things to Shopify. A plan says how the product can be bought, a contract records the agreement, and every charge is a separate attempt to collect money. Knowing which is which makes it easier to read what your admin shows you when a payment fails or a subscriber goes quiet.

Selling plans

Shopify’s developer documentation describes two types of selling plan.

• Pay-per-delivery. “Pay for products for each delivery. New orders are created at regular intervals.”
• Pre-paid. “Make a single payment upfront and receive products on a regular cadence until the order is fulfilled.”

The type decides how often you ask for money. A pay-per-delivery plan collects at every delivery, so there are more moments when a payment can fail. A pre-paid plan collects once at the start. That comparison is 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. The details are in duplicate profiles and subscription contracts.

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.

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 go wrong most often, 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.

In MergeGuard’s demo store: 412 subscribers → 38 with a second account → 21 showing signs Demo store (Northsail Supply).

Take the self-check below to see which gap to close first.