Subscriptions & selling plans
Peregrine renders subscriptions itself. Install a subscriptions app, attach a plan to a product, and the delivery options appear on the product page, in the cart and on the order — no app block to place, no second design to reconcile with your theme.
What you need
Peregrine reads Shopify's selling plans, which is the platform's own way of describing "buy this on a schedule". Any app that creates them works — Shopify Subscriptions is free and is what the theme is tested against.
- Install a subscriptions app.
- Create a plan group ("Deliver every month", "Every 3 months", and so on) and attach it to the products you want it on.
- That is the whole setup. The theme picks the plans up automatically.
Products without plans render nothing at all — not an empty heading, not a blank row. You can leave the block in your product template permanently and it will only appear on the products that actually offer a subscription.
The Subscription options block
In the theme editor, open a product template, and add the Selling plans block to the product section — it sits alongside Price, Variant picker and Buy buttons, and you can position it anywhere in the information column. Most stores put it directly above the Buy buttons.
Each plan is shown as a choice the shopper can select. If the product also allows a normal one-off purchase, One-time purchase is listed first and selected by default, so nobody is opted into a subscription by accident. Where a product is subscription-only — set in your app as "requires a selling plan" — the one-time option is not offered and the first plan is pre-selected instead.
Settings
| Setting | What it does |
|---|---|
| Heading | The title above the options. Leave blank for "Purchase options". |
| Show price per option | Prints each option's price next to it, so the shopper can compare a one-off purchase against a subscription without doing the arithmetic. On by default. |
| Show savings | Adds a Save x% badge to any plan that costs less than buying once. On by default. |
| Show plan description | Shows your app's description for the selected plan — "Cancel anytime", "Free delivery on every order". Appears under the selected option only, so the list stays readable. On by default. |
| Switch to a dropdown above | How many plans a group can hold before the whole thing collapses into a single dropdown. Default 4. A list of three delivery frequencies reads well; a list of twelve does not. |
Prices, and the two numbers that can differ
A subscription price is not always one number. A prepaid plan charges for several deliveries up front, so what the shopper pays today and what each delivery costs are different figures — and showing only one of them is how stores get chargebacks.
Peregrine shows both whenever they differ: the amount due today, and the per-delivery price beside it. Where they are the same — an ordinary "deliver monthly, pay monthly" plan — only one price is shown, because a second identical figure is just noise.
The saving is calculated against the plan's own compare-at price, so it reflects what the app actually configured rather than a percentage the theme has invented.
What happens when the shopper changes variant
This is the part worth understanding, because it is where subscription support usually goes wrong.
Plans belong to variants, not to products. A plan can apply to the 250g bag and not the 1kg one. Peregrine lists only the plans the currently selected variant can actually be bought on, so a shopper is never shown a delivery schedule that will be rejected at checkout.
The consequence is honest but occasionally surprising: if a shopper picks a subscription and then switches to a variant that has no such plan, the selection drops back to a one-time purchase. That is deliberate. The alternative — keeping a selection that no longer exists — produces a checkout error the shopper cannot understand or fix.
The chosen plan is carried in the page address, so a subscription selection survives a refresh and can be linked to or shared.
Express checkout buttons
Shop Pay, PayPal and the other one-tap buttons are hidden while a subscription is selected. Those buttons skip the cart entirely, and skipping the cart is exactly what would lose the delivery schedule — the shopper would tap Shop Pay expecting a subscription and receive a single order. They return the moment One-time purchase is selected again.
In the cart and after the order
- Cart — a subscription line names its plan, and shows the per-delivery price where it differs from the amount being charged. Both the cart page and the slide-out cart do this.
- Sticky add-to-cart bar — follows the selection automatically, including the price, so the bar and the main buy area can never disagree.
- Order page — the customer's order in their account names the plan against each line, so "why am I being charged again" has an answer they can find themselves.
Shopify itself adds a short notice at checkout explaining the recurring charge and the cancellation terms. That is Shopify's, not the theme's, and it cannot be styled or removed — nor should it be.
Testing it before you launch
Attach a plan to one product and walk the whole path: select a plan, check the price and saving, change variant to one the plan does not cover and confirm it drops to one-time honestly, then add to cart and confirm the cart names the plan. It is worth placing one real test order — a subscription that looks right on the product page and arrives at checkout as a single purchase is a bug you want to find yourself.
See also: Product page for the block's position in the information column, and Cart for how subscription lines are shown.