Shopify Selling Plans Explained (Groups, Policies and Contracts)

If you are evaluating subscription apps or debugging a subscription setup, it helps to know what the underlying Shopify objects actually are. There are four, and the relationships between them explain most of the behaviour you will run into.

Selling plan

A selling plan is one way to buy a product. It carries:

• A delivery policy — how often the product ships
• A billing policy — how often the customer is charged
• A pricing policy — the adjustment applied, as a percentage, a fixed amount off, or a fixed price

Delivery and billing are separate on purpose. A prepaid plan bills once and delivers six times; those are two different policies on the same plan.

Selling plan group

Plans are attached to products through a selling plan group. The group is what appears on the product page as a set of options — “Deliver every 2 weeks / 4 weeks / 8 weeks” is one group with three plans in it.

A product can have several groups, which is how you offer both “Subscribe & Save” and “Prepaid 6 months” side by side as distinct choices.

This is also why a product with no group shows no subscription widget: the widget renders the group, and with no group there is nothing to render. It is the most common reason a merchant installs a subscription app and sees nothing change on the storefront.

Subscription contract

When a customer checks out using a selling plan, Shopify creates a subscription contract. This is the live agreement: the customer, the line items, the delivery address, the payment method reference, the next billing date and the status.

The important property: the contract is a Shopify object in your store. It is not a row in your subscription app’s database. If you uninstall the app, the contracts still exist. That is a meaningful difference between apps that use Shopify’s subscription APIs and apps that reimplement subscriptions on top of their own recurring charges.

Billing attempt

On the billing date, a billing attempt is created against the contract. Shopify uses the vaulted payment method to take the money and, on success, creates an order.

The app does not see the card. It asks Shopify to attempt a charge and receives the outcome by webhook. This is why a well-built subscription app needs no PCI scope — it never touches a payment instrument.

A failed attempt returns an error code, and the sensible responses differ by code. An insufficient_funds is worth retrying; an invalid_payment_method needs the customer to act. See payment retry schedule.

How they fit together

Product
  └─ Selling plan group ("Subscribe & Save")
       ├─ Selling plan (every 2 weeks, 10% off)
       └─ Selling plan (every 4 weeks, 15% off)

Customer checks out with a plan
  └─ Subscription contract (their agreement)
       └─ Billing attempt (each cycle)
            └─ Order

Practical consequences

Changing a plan does not change existing contracts. Editing a selling plan changes what new subscribers get. Existing contracts keep the terms they were created with. If you raise prices, you need to decide explicitly whether to migrate existing subscribers, and doing so may require re-authorisation depending on your market.

Deleting a plan with live contracts is dangerous. The contracts reference it. Good apps stop you; the API will not always.

One product, many groups, is fine. Offering pay-as-you-go and prepaid on the same product is two groups, not a hack.

Orders from subscriptions are ordinary orders. They appear in your Shopify admin, work with your fulfilment apps, and can be tagged so you can filter them — which you should do.

Frequently asked questions

What is the difference between a selling plan and a subscription contract?

A selling plan is the offer — the frequency, discount and billing rules attached to a product. A subscription contract is what exists after a customer buys using that plan: their specific recurring agreement, with their address, payment method and schedule.