Skip to content

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:

SavingHow it is calculatedSource
DeliveryShipping rate × number of subscription unitsShop 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 lineStorefront 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 ​

StoreTheme-side hookTheme ID setting
My Perfect PetNone. 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 SnoutssyncThemeAttribute 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:

  1. The theme writes the published theme's ID into the cart attribute _theme_id.
  2. 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.
  3. 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
PieceFile
Extension logicextensions/subscription-savings/src/Checkout.jsx (Preact, @shopify/ui-extensions 2026.7)
Extension config (settings, metafields, capabilities)extensions/subscription-savings/shopify.extension.toml
App configshopify.app.toml (committed; client_id of the Checkout Savings app, no scopes)
Teststest/rate.test.mjs, test/build.sh, stubs in test/stub/

Key rules in Checkout.jsx:

  • Only lines whose selling plan has recurringDeliveries = true count. 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") and money ({"amount":"24.95",...}) metafield types are accepted.

Where it's deployed ​

Repositorygithub.com/crupko93/Checkout-Savings, branch master
Shopify app recordCheckout Savings, client_id c042c837a14ce46801cab5c8874f7eb5
DistributionCustom distribution with Allow multi-store installs for one Plus organization, so one deploy updates every store it is installed on
Extensionsubscription-savings (name "Checkout Savings", API version 2026-07)
HostingShopify 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.

Shopify admin → Settings → Custom data → Shop → Add definition:

FieldValue
Namespace and keycustom.shipping_cost
TypeDecimal (number_decimal)
Valuee.g. 24.95
AccessStorefront / 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.

  1. Shopify admin → Settings → Checkout → Customize.
  2. In the checkout editor, open Apps (or Add app block) and add Checkout Savings.
  3. Drag it into the order summary, near Total.
  4. Fill in the settings below, then Save.

Block settings ​

SettingIDTypeDefaultNotes
Shipping cost per itemshipping_costDecimal(empty)Fallback only. Ignored whenever the shop metafield custom.shipping_cost holds a number.
Theme IDtheme_idText(empty = every theme)Show only for carts from these theme IDs, comma-separated. Needs the theme to write _theme_id.
HeadingheadingText(empty)Blank uses a default that matches the savings in the cart.
MessagemessageText(empty)Supports the placeholders below. Blank uses a default.

Message placeholders ​

PlaceholderValue
{{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 hasHeadingMessage
Delivery saving onlyFree shipping on your subscriptionYou're saving {{savings}} on delivery for this order.
Price saving onlySubscription savingsYou're saving {{subscriptionSavings}} with your subscription.
BothSubscription savingsYou'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 ​

bash
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 deploy
  • npm run deploy publishes 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 rewrites shopify.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:

WhatWhy
"workspaces": ["extensions/*"] in the root package.jsonWithout 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 dependencyOptional peer of @shopify/ui-extensions that the Preact entry imports directly.
[[extensions.targeting.metafields]] block for custom.shipping_costShopify only delivers metafields declared there. Without it shopify.appMetafields is empty.

Testing ​

bash
npm test

test/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;
  • fillTemplate substitutes known placeholders and leaves unknown ones;
  • the theme filter matches comma- or space-separated IDs and blank means "all".

Manual check on a store:

  1. Add a subscription product to the cart (on Super Snouts, from the theme listed in Theme ID).
  2. Go to checkout. The banner shows before any address is entered.
  3. A one-time-only cart shows no banner.
  4. Place a test order. The order's Additional details must not show _theme_id.

Troubleshooting & known limits ​

SymptomCause
Nothing renders, no errorThe block is not placed in the checkout editor, or the cart has no subscription lines.
Banner shows the fallback rate, not the metafieldThe custom.shipping_cost definition lacks storefront/extension read access, or the value is not a number.
Banner hidden on Super SnoutsTheme 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 ordersThe block is not placed in checkout, or the buyer used an accelerated checkout button outside checkout.
Price saving shows 0 brieflyThe 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.

Antelope Themes Documentation

Enter the password to access this site.