# Supply calculator and subscriptions

Chapter 10 of the Dose user guide.

Supplements run out on a schedule. The supply calculator works out how long a bottle lasts at the shopper's daily dose and picks the delivery plan that brings the next one before the last runs out.

## What shoppers see

Inside the **Subscribe and save** option on the product page:

* **Gummies a day** (or "Capsules a day", "Scoops a day", "Servings a day", from the serving size): a row of choices such as **2 · 4 · 6**, each with its dots.
* **A calendar of dots**, one per day, filled for the days the bottle lasts, with the delivery day ringed, and "Day 1 … Next bottle arrives before day 30".
* **The result**: "This bottle lasts 30 days. Delivery set to match."
* **Deliver every [30 days ⌄]** already chosen.

Picking 4 a day empties half the calendar and says "One bottle lasts 15 days. Use 2 bottles to match a 30-day delivery.", with a **Use 2 bottles** button that sets the quantity to 2. Changing the quantity or the size works it out again, and screen readers hear the new result. The hint always matches the delivery the shopper has chosen (with 60 days picked: "Use 4 bottles to match a 60-day delivery"); with **One-time purchase** chosen there's no delivery, so the hint and the ringed delivery day don't show.

On a product without delivery plans, the calculator shows the choices and "This bottle lasts 30 days." on its own. On the home page, the **Supply promo** shows the same calculator for one product (below).

## How it works it out

1. **Servings** = the selected variant's `custom.servings` when it has one, else the product's.
2. **Daily servings** = the shopper's choice, starting at `custom.daily_servings` (1 without it).
3. **Days** = servings × quantity ÷ daily servings, rounded down.

The choices come from the serving size, the first line of `custom.supplement_facts` (chapter 8). When the serving size counts pieces (gummy, capsule, softgel, tablet, chew or drop, singular or plural), the choices are pieces: "2 gummies" gives **2 · 4 · 6** with **Most servings a day** at 3. Any other word counts servings: "1 scoop (40 g)" gives **1 · 2 · 3**, labelled "Scoops a day". With no serving size, or one without a number first, it's "Servings a day".

The calendar shows one dot a day up to 60 days; from 61 to 180 days one dot a week ("Each dot is a week"); over 180 days no calendar and "This bottle lasts over 6 months."

## Which plan is chosen

**Each plan's length in days** comes from the first number and unit in the plan's name or its options: `day`, `days` or `d` count as one day, `week`, `weeks`, `wk` or `w` as seven, and `month`, `months`, `mo` or `m` as 30. "Deliver every 30 days" is 30, "Every 4 weeks" 28, "2 months" 60, "6wk" 42. A number followed by anything else, such as "15%" or "200 mg", is skipped. A plan with no number and unit, such as "Monthly", takes its days from **Plan lengths in days** (Theme settings › Subscriptions) by its place in its group: with "30, 60, 90", the first plan is 30 days, the second 60 and the third 90.

**The pick**: the longest plan no longer than the supply plus **Supply tolerance** (2 days by default), so the next delivery lands before the last bottle runs out. If every plan is longer, the shortest, with the "Use 2 bottles" hint. Only the selected variant's plans count, and only plans that deliver more than once.

**The shopper always wins.** The calculator chooses a plan when the page opens and again when the daily choice, the quantity or the size changes, but only until the shopper picks a purchase option themselves; after that it never changes their choice, including when they come back with the browser's Back button or reload the page. It never chooses over a link that names a plan (`?selling_plan=`). Turn **Preselect the matching delivery** off to leave the choice to shoppers entirely.

**Worked examples**, with plans "Deliver every 30 days", "Deliver every 60 days" and "Deliver every 90 days", a tolerance of 2 and the Dose preset's container words "bottle, tub, box":

| Product | Serving size, servings | Shopper picks | Days | Plan chosen |
| --- | --- | --- | --- | --- |
| Wind-down gummies | 2 gummies, 30 | 2 a day (1 serving) | 30 | **30 days** (30 is within 30 + 2) |
| Wind-down gummies | 2 gummies, 30 | 4 a day (2 servings) | 15 | No plan within 17, so the shortest, **30 days**, with "Use 2 bottles"; at quantity 2 it lasts 30 days |
| Sunny D3 + K2 | 1 capsule, 60 | 1 a day | 60 | **60 days** |
| Magnesium glycinate, on plans "Every 4 weeks" and "Every 8 weeks" | 3 capsules, 30 | 3 a day | 30 | **4 weeks** (28 is within 32; 56 isn't) |
| Plant protein | 1 scoop (40 g), 25 | 1 scoop | 25 | No plan within 27, so **30 days**, with "Use 2 tubs" |
| Collagen + C, no plans | 1 scoop (10 g), 30 | 1 scoop | 30 | No plans: "This tub lasts 30 days." |

## Container words

**Container word** (Theme settings › Subscriptions) words the result: "This bottle lasts 30 days", "Use 2 bottles". You can list several, separated by commas; the first is the default, and another wins on the products it suits:

* a word that appears in the product's **type** or **title** (a product called "Greens tub" is a tub);
* otherwise, for a powder (`custom.format` contains "powder", or a serving size in scoops), the first of `tub`, `jar` or `pouch` in your list;
* for stick packs (format or serving size "stick"), the first of `box` or `pack`.

With "bottle" alone everything is a bottle. The plural adds "es" after s, x, ch or sh ("boxes", "pouches"), else "s".

## Delivery plans need a subscription app

**Dose shows delivery plans; it doesn't create them.** Plans (Shopify calls them selling plans) come from a subscription app: Shopify's free **Shopify Subscriptions** app, or another subscription app. The app creates the plans and their discounts, takes the repeat payments, and gives shoppers the account page where they pause, skip or cancel. Without one, products have no plans: the buy box shows no purchase options and the calculator shows how long a bottle lasts and nothing more.

To set it up:

1. Install a subscription app from the Shopify App Store.
2. In the app, create a plan with deliveries every 30, 60 and 90 days (or the intervals you offer) and the discount you offer, such as 15%. Add your supplements to it.
3. Name the plans with a number of days, weeks or months ("Deliver every 30 days", "Every 4 weeks"). If your app names them "Monthly" or "Every month", set **Plan lengths in days** to match their order, such as `30, 60, 90`.
4. Open a product in the theme editor: **Subscribe and save** should show "Save 15%", the calculator and a plan already chosen.

The "Save 15%" tag is worked out from Shopify's own plan price against the one-time price, so it always matches your app. The words in the Subscribe and save card, "Free shipping. Pause, skip or cancel any time.", are true only if your shipping rates and your app make them so: "Free shipping." goes when **Subscriptions ship free** is off, and the rest can be changed under **Edit default theme content** (chapter 15).

A product with several plan groups shows one **Subscribe and save** card per group, under the group's own name. A plan the selected variant isn't sold with is disabled and says "Not available for this variant".

## Settings

**Theme settings › Subscriptions**: **Plan lengths in days**, **Supply tolerance**, **Subscriptions ship free** and **Container word** (chapter 2).

The **Supply calculator** block (Product and Featured product sections):

| Setting | Default | What it does |
| --- | --- | --- |
| Heading | "How long will it last?" | Shown when the calculator stands on its own; read by screen readers inside the Subscribe and save card |
| Most servings a day | 3 | 1 to 6. The shopper picks from one serving a day up to this many. |
| Show the dot calendar | On | |
| Show the equation | Off | "60 gummies ÷ 2 a day = 30 days" |
| Preselect the matching delivery | On | Chooses the delivery that matches the daily dose until the shopper picks a purchase option themselves |

Keep the block anywhere in the Product section. On a product with plans it shows inside the **Subscribe and save** card, so the **Buy buttons** block's **Show subscription options** must be on; on a product without plans, or with that setting off, it shows where you placed it. It shows nothing on a product without `custom.servings`.

The same rule drives the **serving chip** on cards ("2 a day · 30 days": pieces a day are the serving size's count × daily servings, with a dot for each, up to four), the cart line ("2 a day · lasts 30 days", at the line's quantity), the card's **Quick add the subscription** and the goal finder's plans. These use the product's daily servings, not a choice the shopper made in the calculator.

## The Supply promo section

The home page's "Never run out" band: your words, the sum and three ticks on the left, and on the right a white card with one product, its calculator, the delivery intervals as chips ("Deliver every 30 days · 60 days · 90 days"), "Matched to 2 gummies a day", and its own button, "Subscribe · $28.90 every 30 days", which adds the product on the chosen plan.

| Setting | Default | What it does |
| --- | --- | --- |
| Background | Second colour block | |
| Show the section marker, Filled marker dots | On, 3 | |
| Eyebrow | "Supply calculator" | |
| Heading | "Never run out" | |
| Text | "Tell us how many you take each day. We'll work out how long a bottle lasts and time your deliveries to match. Pause, skip or change it whenever you like." | |
| First tick, Second tick, Third tick | "Delivery set from your daily dose", "15% off every delivery", "Free shipping" | State only what your subscription app and shipping rates actually offer |
| Product | | Under **Calculator**. A product with `custom.servings`. |
| Button label | "Subscribe" | The price and plan are added after it |

**Until you choose a product with `custom.servings`, shoppers see only the words**, across the full width. In the theme editor the card shows a sample, with the button disabled. Choose your best seller, or delete the section.

## In the theme editor

On a product without `custom.servings`, the theme editor shows the calculator with a sample (Wind-down gummies: 30 servings of 2 gummies, plans of 30, 60 and 90 days) and a "Sample" tag. Shoppers see nothing until you fill in the metafields.