Checkout Savings
Overview
Checkout Savings is a checkout UI extension that shows subscription buyers how much their subscription saves them. It renders as a green success banner in checkout, at the first step, before a delivery address exists.
It counts two savings, each only where it applies:
| Saving | How it is calculated | Source |
|---|---|---|
| Delivery | Shipping rate × number of subscription units | Shop metafield custom.shipping_cost, falling back to the block's Shipping cost per item setting |
| Subscription price | (one-time price − subscription plan price) × quantity, per subscription line | Storefront API query for each subscription variant's price and selling-plan price adjustments |
A store where subscriptions cost the same as one-time purchases shows only the delivery saving. A store without a shipping rate shows only the price saving. A cart with no subscription lines shows nothing.
Why it exists: the cart drawer shows "You save $24.95". Shopify's checkout shows free subscription shipping only as a $0.00 / "Free" shipping line, and only after the buyer enters an address. The banner states the amount up front.
Where it's used
| Store | Theme-side hook | Theme ID setting |
|---|---|---|
| My Perfect Pet | None. The MPP theme does not write _theme_id. The theme's own shipping value is the theme setting settings.shipping_cost (24.95), used by the mini cart, PDP and PLP. | Leave blank (a set filter would hide the banner on every MPP cart). |
| Super Snouts | syncThemeAttribute in src/vue/store/cart.js writes window.Shopify.theme.id into the cart attribute _theme_id once per page load, for carts with items. Only Theme B (staging) has this code; Theme A (master) does not write the attribute. | Set to the theme ID(s) that should show the banner. |
Theme ID filter on Super Snouts
A Theme ID filter only matches carts from a theme that writes _theme_id. Carts from Theme A (master) never carry the attribute, so a set filter hides the banner for them.
Related theme pages: MPP Cart & Checkout, Super Snouts Cart & Checkout.
How the Theme ID filter works
Checkout does not know which theme the buyer shopped on, so the storefront has to say so:
- The theme writes the published theme's ID into the cart attribute
_theme_id. - When checkout loads, the extension reads the attribute, stores the value in extension storage for the rest of that checkout, and removes the attribute (
applyAttributeChange). It does this whatever the Theme ID setting is, so the value never ends up on the order. - The block shows only if the stored theme ID is in the comma-separated Theme ID setting. Blank means "every theme".
Consequences:
- Keep the block placed in checkout on every store whose theme writes
_theme_id, even with the Theme ID blank. Remove the block and nothing strips the attribute. It then shows in the order's Additional details. - Accelerated checkout started outside checkout (Apple Pay / Google Pay / Shop Pay buttons on the product or cart page) never renders the extension, so the attribute would survive onto the order. The Super Snouts theme does not render those buttons. Keep it that way, or stop writing the attribute.
- Write the attribute on every theme a buyer can shop on, not only the target one. Otherwise carts from the other themes keep a stale ID.
Architecture
Storefront theme (Super Snouts)
└── cart.js syncThemeAttribute ──► cart attribute _theme_id
Checkout (Shopify-hosted, sandboxed)
└── extension "subscription-savings" target: purchase.checkout.block.render
├── reads shopify.lines, shopify.settings, shopify.attributes
├── reads shopify.appMetafields ← shop metafield custom.shipping_cost
├── query Storefront API (api_access = true) ← variant price + sellingPlanAllocations
└── removes _theme_id, keeps it in extension storage| Piece | File |
|---|---|
| Extension logic | extensions/subscription-savings/src/Checkout.jsx (Preact, @shopify/ui-extensions 2026.7) |
| Extension config (settings, metafields, capabilities) | extensions/subscription-savings/shopify.extension.toml |
| App config | shopify.app.toml (committed; client_id of the Checkout Savings app, no scopes) |
| Tests | test/rate.test.mjs, test/build.sh, stubs in test/stub/ |
Key rules in Checkout.jsx:
- Only lines whose selling plan has
recurringDeliveries = truecount. Pre-orders and try-before-you-buy do not. - Shipping is charged per unit, so a quantity-2 subscription line saves 2 × the rate.
- The subscription price saving uses the plan price, not the line total, so a discount code never inflates it.
- Until the Storefront query returns, lines count as 0 rather than guessing.
- The shop metafield wins over the setting whenever it holds a number. A blank or malformed metafield falls through to the setting. Both
number_decimal("24.95") andmoney({"amount":"24.95",...}) metafield types are accepted.
Where it's deployed
| Repository | github.com/crupko93/Checkout-Savings, branch master |
| Shopify app record | Checkout Savings, client_id c042c837a14ce46801cab5c8874f7eb5 |
| Distribution | Custom distribution with Allow multi-store installs for one Plus organization, so one deploy updates every store it is installed on |
| Extension | subscription-savings (name "Checkout Savings", API version 2026-07) |
| Hosting | Shopify hosts the extension. No server, no Vercel project, no database. |
Plus only
Checkout blocks on the information/shipping/payment steps require Shopify Plus. The app's multi-store install also relies on the stores sharing one Plus organization.
How to use (merchant / admin)
1. Install the app
Install from the custom distribution link in the Partner Dashboard. With multi-store installs enabled, the same app installs on every store in the Plus organization.
2. Set the shipping rate (recommended)
Shopify admin → Settings → Custom data → Shop → Add definition:
| Field | Value |
|---|---|
| Namespace and key | custom.shipping_cost |
| Type | Decimal (number_decimal) |
| Value | e.g. 24.95 |
| Access | Storefront / extension read access. Without it the extension silently falls back to the block setting. |
A store without free subscription shipping leaves it unset.
One source of truth
The same metafield can replace settings.shipping_cost in the theme (shop.metafields.custom.shipping_cost in Liquid), so PDP, cart and checkout all use one value. Until a theme reads it, keep the theme setting and the metafield equal by hand.
3. Place the block in checkout
Shopify does not let apps place checkout blocks programmatically. Until someone places it by hand, the extension renders nothing, with no error anywhere.
- Shopify admin → Settings → Checkout → Customize.
- In the checkout editor, open Apps (or Add app block) and add Checkout Savings.
- Drag it into the order summary, near Total.
- Fill in the settings below, then Save.
Block settings
| Setting | ID | Type | Default | Notes |
|---|---|---|---|---|
| Shipping cost per item | shipping_cost | Decimal | (empty) | Fallback only. Ignored whenever the shop metafield custom.shipping_cost holds a number. |
| Theme ID | theme_id | Text | (empty = every theme) | Show only for carts from these theme IDs, comma-separated. Needs the theme to write _theme_id. |
| Heading | heading | Text | (empty) | Blank uses a default that matches the savings in the cart. |
| Message | message | Text | (empty) | Supports the placeholders below. Blank uses a default. |
Message placeholders
| Placeholder | Value |
|---|---|
{{savings}} | Delivery saving |
{{subscriptionSavings}} | Subscription price saving |
{{totalSavings}} | Both together |
Unknown placeholders are left as typed, so a typo shows up in checkout instead of rendering blank.
Default wording
| Cart has | Heading | Message |
|---|---|---|
| Delivery saving only | Free shipping on your subscription | You're saving {{savings}} on delivery for this order. |
| Price saving only | Subscription savings | You're saving {{subscriptionSavings}} with your subscription. |
| Both | Subscription savings | You're saving {{totalSavings}} on this order: {{subscriptionSavings}} with your subscription and {{savings}} on delivery. |
Amounts are formatted in the checkout currency and locale.
How to update & deploy
git clone git@github.com:crupko93/Checkout-Savings.git
cd Checkout-Savings
npm install # root workspace also installs extensions/* deps
npm test # bundle + node assertions
npm run deploy # = shopify app deploynpm run deploypublishes a new app version to the Checkout Savings app record. Every store with the app installed gets it. Block settings (heading, message, fallback rate, Theme ID) are saved per store in that store's checkout editor and survive deploys.- There are no environment variables and no secrets in this project.
npm run link(shopify app config link) is only needed to point the project at a different app record. It rewritesshopify.app.toml.npm run dev(shopify app dev) previews against a dev store. A dev store is not Plus, so checkout block placement may not be previewable there. Verify on the real store with a draft checkout profile before publishing.
Build wiring that must not be lost in a refactor:
| What | Why |
|---|---|
"workspaces": ["extensions/*"] in the root package.json | Without it npm install at the root never installs the extension's own deps, and the bundler fails with Could not resolve "preact". |
extensions/subscription-savings/tsconfig.json (jsx: react-jsx, jsxImportSource: preact) | esbuild reads JSX settings from tsconfig. Without it the build fails with Could not resolve "react/jsx-runtime". |
@preact/signals as a direct dependency | Optional peer of @shopify/ui-extensions that the Preact entry imports directly. |
[[extensions.targeting.metafields]] block for custom.shipping_cost | Shopify only delivers metafields declared there. Without it shopify.appMetafields is empty. |
Testing
npm testtest/build.sh bundles Checkout.jsx with stubbed Shopify and Preact imports, then test/rate.test.mjs runs the pure helpers under plain Node. It checks that:
- the metafield beats the setting; a blank or malformed metafield falls through;
- product-scoped and wrong-namespace metafields are ignored;
- quantity multiplies; pre-orders do not count; a mixed cart counts only subscription units;
- subscription price savings use the chosen plan's price;
fillTemplatesubstitutes known placeholders and leaves unknown ones;- the theme filter matches comma- or space-separated IDs and blank means "all".
Manual check on a store:
- Add a subscription product to the cart (on Super Snouts, from the theme listed in Theme ID).
- Go to checkout. The banner shows before any address is entered.
- A one-time-only cart shows no banner.
- Place a test order. The order's Additional details must not show
_theme_id.
Troubleshooting & known limits
| Symptom | Cause |
|---|---|
| Nothing renders, no error | The block is not placed in the checkout editor, or the cart has no subscription lines. |
| Banner shows the fallback rate, not the metafield | The custom.shipping_cost definition lacks storefront/extension read access, or the value is not a number. |
| Banner hidden on Super Snouts | Theme ID is set, but the buyer's theme does not write _theme_id (see Where it's used), or the ID doesn't match. |
_theme_id appears on orders | The block is not placed in checkout, or the buyer used an accelerated checkout button outside checkout. |
| Price saving shows 0 briefly | The Storefront query hasn't returned yet. Lines count as 0 until it does. |
- One shipping zone assumed. The rate is a single number, but rates can vary by destination and the banner renders before any address is known. If zones differ, use the lowest rate so the claim is never overstated.
- Styling is constrained. Colours and typography come from checkout branding settings. The cart drawer's green cannot be reproduced exactly.
- No A/B measurement. Unlike an Intelligems checkout block, nothing here reports to an experiment.