Tab Commerce
Contact Explore apps

Build your own discount progress bar in a Shopify theme

Tab Promo's Storefront SDK gives your theme the numbers a progress bar needs: how far the cart is toward a spend or quantity threshold, how much is left, and which tier comes next. Your theme's JavaScript reads them straight from your store's App Proxy, with no API key or backend, and draws the bar in your own design. A fact can also carry the rule's checkout label as written in Tab Promo, so the bar can reuse that wording. The bar only displays the offer; the discount itself is applied by Shopify checkout.

Install Tab Promo About Tab Promo

Plan: Pro — $99/month (on Free and Starter, the theme app embeds include a ready-made progress message)

See it work

Same facts, your design.

theme/assets/promo.js

import { init } from
  '@tabcommerceio/promo-sdk'

const promo = init({
  proxyBase: '/apps/tab-promo',
})

promo.mount({
  request: { surface: 'cart' },
  render({ promos }) {
    // progress, ladder, status
    promos.forEach(drawBrandUi)
  },
})

SOLÈNE

Almost there. $28 from 10% off your bag.

Checkout decides the priceShopify calculates every discount — the UI only shows the offer.

Response

Everything a progress bar needs.

A spend threshold comes back as a progress fact: where the cart is, the target, what remains, the percentage and the reward. display.message is the rule's checkout label, as written in Tab Promo. Your theme can show it or write its own copy, such as "$28 from 10% off".

{
  "campaign_id": "0192f0a3-d3a1-7000-8000-000000000002",
  "primitive": "progress",
  "unit": "money",
  "scope": "cart",
  "currency": "USD",
  "current": 7200,
  "target": 10000,
  "remaining": 2800,
  "progress_percent": 72,
  "achieved": false,
  "reward": { "kind": "order_percentage", "percentage": 10 },
  "display": { "message": "10% off orders over $100" }
}

Examples

Offers you can set up today.

Spend threshold

Cart subtotal at least $100 → 10% off the order

At $72 the progress fact reads $72 of $100, $28 remaining, 72%. Your bar fills to 72% and says "$28 to go".

Free shipping bar

Cart subtotal at least $75 → Free shipping

At $60 the bar shows $15 to go (80%). Once the cart passes $75 the fact turns achieved, so the bar can switch to a confirmation.

Quantity tier ladder

Buy 2 → 10% off, 3 → 15%, 4+ → 20% (counted per variant)

With 2 of the selected variant in the cart, the ladder lists all three tiers, marks 10% as reached and shows 1 more item to reach 15%.

Two spend steps

Two rules in one campaign: Cart subtotal at least $50 → $5 off, at least $100 → $15 off

Each step is its own fact. At $64 the $50 step is achieved and the $100 step shows $36 to go, so you can draw both on one bar.

Setup

How to set it up.

  1. Create the threshold or tier rule. For a spend bar, add a Cart subtotal condition with "at least" or "greater than" and pick the reward. For a tier ladder, use a product discount with the Quantity tiers mode.
  2. Publish it. Set the rule to Active, open Publish and click Publish now. Only live campaigns return facts.
  3. Check the numbers in the sandbox. On the Storefront page, click Open sandbox, build a sample cart and confirm the progress or ladder values your bar will receive.
  4. Mount the SDK where the bar lives. Mount on the cart surface for a drawer bar or the product surface for a tier table. Draw from current, target, remaining and progress_percent, or from rungs and remaining_to_next for a ladder.
  5. Keep it in step with the cart. The SDK refreshes on common theme cart events. After your theme changes the cart some other way, call notifyCartChanged. Then test with a real checkout.

Good to know

Where it stops.

  • A progress bar comes from a threshold that must be met ("at least" or "greater than") in conditions joined by All. Thresholds inside Any or None groups, and upper limits, show as eligible or not, with no progress track.
  • Tier ladders come from quantity tiers on a product discount, and on product pages from tiered free gifts in one campaign. Spend steps are separate rules, each with its own progress fact.
  • Money values arrive as whole minor units in the shopper's currency, for example 2800 for $28.00. Format them with the currency's own decimal places.
  • The bar describes the offer; it does not apply it. If the request fails, the SDK returns nothing and your bar should hide rather than show old numbers as current.

Plan: Pro — $99/month (on Free and Starter, the theme app embeds include a ready-made progress message). Compare plans

Storefront SDK Storefront promotion API Quantity tiers and discount combinations

FAQ

Common questions.

Can I build a free shipping progress bar?

Yes. A Free shipping rule with a Cart subtotal threshold returns a progress fact like any other spend threshold, with the reward marked as free shipping.

Do I need an API key or a backend server?

No. The SDK calls your store's Shopify App Proxy from the browser. Shopify signs each request, so there is no key to store and nothing for you to host.

Does the bar update when the cart changes?

Yes. The SDK listens for common cart events such as cart:updated and cart:refresh, and refreshes after its own gift and top-up actions. Call notifyCartChanged after any other cart change.

Can I do this on the Starter plan?

Not with your own code; the SDK needs Pro or Growth. On Free and Starter, the Tab Promo theme app embeds show a built-in "Spend $X more to unlock" message and progress bar, with text and display settings in the theme editor.

Does Tab Promo work with a custom theme?

Yes. The theme app embeds work in Online Store themes, and with the SDK a developer can replace them with fully custom UI. It does not cover Hydrogen or other headless storefronts.

Which currency does the bar use?

The shopper's cart currency, in minor units. If a money threshold can't be converted reliably, that fact is left out rather than shown with a wrong amount.

More with Tab Promo

Related guides.