Storefront
Storefront Offer Card
Add the xDiscount offer block to your theme so shoppers see each live offer, its conditions, its countdown and the gift picker before checkout.
What the Offer Card Is
Your automatic discounts apply at checkout on every plan, with nothing for shoppers to enter. The storefront offer card is the other half of that. It is a small card on your product page that tells shoppers about the offer before they reach checkout.
The card reads exactly the same configuration the checkout discount reads. That is deliberate. What a shopper is shown and what they are charged cannot drift apart.
Two things to know before you start:
- The offer card is included on every plan, Free included. Your discounts apply automatically at checkout whether or not the card is on your theme, and the card only changes what shoppers see beforehand.
- The card is a theme app block. It does not appear until you add it to your theme yourself, in the Shopify theme editor. Nothing about a discount changes when you add it.
Buy X get Y needs this card
A Shopify discount function cannot put an item into a cart, so the card’s gift picker is what adds the gift. xDiscount says so on the discount form: “Buy X get Y needs the storefront offer card installed on your theme. A discount cannot add an item to the cart on its own, so the card is what puts the gift there.”
A free gift can also be added to the cart automatically, by the cart progress bar, on a discount for specific products, collections or all products. The card then shows “Your free gift is added to your cart automatically” instead of the gift picker. See Cart Progress Bar and Automatic Gift below.
Adding the Block to Your Theme
Open Settings
In xDiscount, open Settings.
Open the Storefront features tab. The offer card is its first card, Offer card on product pages.
Check the badge
The card’s badge tells you whether the block is already on your live theme. The three readings are in the table below.
Click Add to theme
Your Shopify theme editor opens in a new tab, on the product template, with the xDiscount offer block already placed in a new Apps section. This is the deep link Shopify documents for theme app extensions, so there is nothing to find in the block picker. If the block is not there, because of an older theme or a picker that did not take the link, click Add block and choose xDiscount offer yourself.
Place it and save
Drag the block where you want it. Just under your theme’s Add to cart button is a good place. Click Save in the theme editor.
Go back to xDiscount
The badge flips to On on its own within a few seconds. If it has not caught up, click Check again.
What the badge means:
| Badge | What it means |
|---|---|
| On | The block is on your live theme’s product template and switched on |
| Off | The block is not there, so follow the steps above |
| Couldn’t check | We could not read your theme just now. This is not the same as “not installed”, so click Check again |
Once the block is installed, the button changes to Open theme editor and opens the same template without adding a second copy of the block. An Uninstall button appears in the card. It opens the same editor, because Shopify gives apps no way to remove a block from a theme. The card says so above the button, and once you delete the block there, the badge updates on its own.
You don’t have to remember this on your own
While the block is missing from your live theme, the app reminds you where it matters. The discount form shows a banner every time you create or edit a discount, with a stronger one for Buy X get Y, which can’t deliver its gift without the card. The Discounts page shows one as soon as any discount is Active, because that is the moment shoppers are missing something. Both banners carry the same Add to theme button as Settings and an Open settings link, and both disappear on their own once the block is on your theme. They stay silent when the theme couldn’t be read, so a banner never sends you to add a block you already have.
What the check actually looks at
- Your live, published theme only. If you publish a different theme, add the block there too.
- Your default product template, because the card is a product-page block. If some of your products use an alternate product template, the card still shows wherever you added the block, but the badge only reflects the default one.
- A block that is present but switched off in the theme editor counts as not added.
- A block nested inside a group or another block is still found.
- A theme that predates Online Store 2.0 has no product template of this kind and cannot take app blocks at all, so the badge stays on Off.
- The block is recognised by its own block handle, the
offer_cardinshopify://apps/…/blocks/offer_card/<uuid>. That segment is xDiscount’s own and does not change when the app is renamed or the extension re-registered, so the badge keeps working across upgrades.
Shopify never notifies an app when a theme block is added or removed, so after you click Add to theme xDiscount goes and looks for itself: once after two seconds, then every five seconds, up to twenty times, stopping as soon as the badge changes. After that, use Check again.
The same check on Home
The Home screen’s Getting started list has a matching step, “Show the offer on your product pages”, with an Open settings button. It runs the same theme check as Settings, so the two screens agree on what “added” means, and Home marks that step Couldn’t check when your theme cannot be read.
If a badge ever reads Not on your plan
The card is included on every plan, Free included, with the same badge and the same buttons everywhere. A badge reading Not on your plan can only mean your subscription sits on a plan the app does not recognise. Use Refresh plan under Plans & billing, and if it stays, tell us.
Theme Editor Settings
Select the xDiscount offer block in the theme editor. Its settings are grouped under six headers: Text, Stock line, Conditions, Colours, Size and spacing and Display.
Everything about what the card says about a discount still comes from the discount itself. None of these settings can change an amount, a condition or a date, so the card and checkout cannot disagree.
Text
| Setting | Type | Default | What it does |
|---|---|---|---|
| Details line | Text | (empty) | The small line under each offer’s name. Leave empty for Click to see details |
| No conditions wording | Text | (empty) | Shown in the window when an offer has no conditions. Leave empty for No special conditions required |
| Gift picker label | Text | (empty) | The wording on the gift button and the title of the gift window. Leave empty for Choose your free gift |
Every text setting is optional, and empty means the translated default. That is deliberate. A store in another language is never handed English from a default you did not type.
Stock line
| Setting | Type | Default | What it does |
|---|---|---|---|
| Show stock on the offer | Checkbox | Ticked | Shows how many of the selected variant are in stock on each offer, as Only 7 left in stock, and follows the variant the shopper selects. Nothing is shown at zero, or when stock is not tracked |
| Stock wording | Text | (empty) | Your own wording, with {count} where the number goes. Leave empty for Only {count} left in stock |
The number is your theme’s own stock figure at the moment the page renders. It is only ever shown, and no discount is decided from it.
Conditions
Three checkboxes decide which kinds of condition the window shows, and six optional templates under the same header decide the wording.
| Setting | Type | Default | What it does |
|---|---|---|---|
| Show quantity conditions | Checkbox | Ticked | Whether quantity conditions appear in the window |
| Show cart value conditions | Checkbox | Ticked | Whether cart value conditions appear in the window |
| Show stock conditions | Checkbox | Ticked | Whether inventory conditions appear in the window |
Hiding a condition changes nothing at checkout
The discount still requires it, and shoppers are simply not told. If the only condition an offer has is one you hid, the window shows nothing at all rather than claiming there are no conditions, because that claim would be false and checkout would prove it.
Condition wording. Six optional templates, one per kind of condition, so the window speaks in your words. Each takes {min} and, where it applies, {max} where the numbers go. Leave a template empty for the default wording.
| Setting | Filled in for |
|---|---|
| Quantity, minimum only and minimum and maximum | An item quantity condition with one bound, or with both |
| Cart value, minimum only and minimum and maximum | Cart value conditions. {min} and {max} are filled in your store’s money format, for example $50.00, or 50 EUR on a foreign market, so write the template without a currency symbol |
| Stock, minimum only and minimum and maximum | Inventory conditions |
A condition with Negate this condition ticked uses the same template, wrapped as Not: …. A maximum-only bound, and an older date condition, always use the default wording.
Why there is no template for negated conditions
Shopify allows an app block at most 25 settings and 6 headers, and this block uses 21 settings under all six headers. That is why there is no second set of templates for negated conditions, and why the window’s Conditions heading is not a setting.
The update adds a 22nd setting, Show the price after discount, under Display.
Colours
| Setting | Type | Default | What it does |
|---|---|---|---|
| Text on tiles | Colour | (empty) | The colour written on the filled tiles. Leave empty and the card picks white or near-black to suit your tile colour, so a light tile never gets invisible white text |
| Offer tile colour | Colour | (empty) | The colour each offer tile is filled with. Leave empty for the default violet |
Each offer is a filled, rounded tile, and Offer tile colour is the colour it is filled with. Out of the box that is a violet, #8B5CF6, with white writing. The block has no heading, background or border of its own: the tiles sit directly on your product page, one per offer shown, exactly as xBundle’s do.
Size and spacing
| Setting | Type | Default | What it does |
|---|---|---|---|
| Card width | Select | Full width | Full width, Small (240px), Medium (340px) or Large (400px). This caps each tile, not the block. On Full width the tiles share the row and grow to fill it |
| Corner radius | Range, 0 to 24px in steps of 2 | 12 | How rounded each tile is |
| Padding | Range, 0 to 32px in steps of 4 | 16 | The space between a tile’s edge and its contents |
The offers are laid out as a responsive grid: as many tiles per row as fit at 280px each, wrapping onto the next row below that. A tile lifts slightly when a shopper points at it, and does not move at all for a shopper who has asked their system to reduce motion.
Display
| Setting | Type | Default | What it does |
|---|---|---|---|
| Show countdown | Checkbox | Ticked | Shows a live countdown under any discount with an end date, in your store’s timezone |
| Countdown segments | Select | Days, hours, minutes, seconds | Which segments the countdown shows: Days, hours, minutes, seconds, Hours, minutes, seconds or Minutes, seconds. Days are hidden while there are none left, and hours while there are no hours or days |
| Show the price after discount | Checkbox | Ticked | Shows the selected variant’s price with the offer taken off, and the price per item at each volume step. A price only appears when checkout will charge exactly that amount. See The price after the discount below |
The countdown is a strip of Days / Hours / Min / Sec under the offer, and it counts to the end of the last day in your store’s timezone. The end moment is stamped with your store’s UTC offset, so a shopper in another country sees the same time remaining you do, not their own midnight. The strip turns amber under a day, and red, gently pulsing, under an hour. A shopper who has asked their system to reduce motion sees no pulse.
The countdown only ever describes a discount
Whether an offer appears at all is decided on the server, against your store’s day, by the same comparison checkout makes. A shopper whose device clock is wrong sees wrong digits and the right offers, never an offer checkout would refuse. The Ends today wording is printed on a discount’s final day whether this box is ticked or not.
Whatever you type into any text setting is shown to shoppers exactly as you wrote it, and is escaped before it reaches the page, so a stray quote or angle bracket in your wording can never break the card or your theme.
What Shoppers See
On a product page with at least one live offer, the card shows its offers as a grid of filled, rounded tiles and nothing else: no heading of its own and no frame around the tiles, exactly like the reference app.
The card shows one offer by default: a single tile, for the kind of offer you put first. You can have it show one tile per live offer the product can get instead. Both are explained in One offer or every offer, below. Above the tiles it can also show the price after the discount for the selected variant, also described below.
Each tile reads, left to right: the discount’s name as you typed it on the discount form, the Details line under it, the stock line if you switched it on, and the value large on the right.
| Discount type | What the value says |
|---|---|
| Percentage | 20% off, the number you set, always read between 0 and 100 |
| Fixed amount | $10.00 off, and see the currency section below |
| Buy X get Y | Free gift, or 50% off a gift for a partial gift discount |
| Free shipping | Free shipping |
| Percentage or fixed amount with volume tiers | Up to 15% off, the best step. The steps are listed in the window that opens on click. See Volume tiers below |
Clicking a tile opens a window with the discount’s name, its value, and its conditions under a Conditions heading, in the same order and with the same joins as the discount actually evaluates them. If your discount needs 3 items and the card did not say so, a shopper would only find out at checkout. An offer with no conditions says so.
A discount with volume tiers also lists its steps in the window, before its conditions.
| Condition you set | What shoppers read |
|---|---|
| Item quantity, both bounds | Buy 2 to 5 |
| Item quantity, minimum only | Buy 2 or more |
| Item quantity, maximum only | Up to 5 |
| Cart value, both bounds | Spend $50.00 to $200.00 |
| Cart value, minimum only | Spend $50.00 or more |
| Cart value, maximum only | Spend up to $200.00 |
| Inventory, both bounds | While stock is between 5 and 10 |
| Inventory, minimum only | While at least 5 are in stock |
| Inventory, maximum only | While stock is 10 or fewer |
| An older date condition, both dates | 2026-09-01 to 2026-09-30 |
| An older date condition, start only | From 2026-09-01 |
| An older date condition, end only | Until 2026-09-30 |
| Negate this condition ticked | Not: Buy 2 or more |
Rows after the first carry their own joining word, and or or, on the line above them, matching the way conditions are read top to bottom on the discount form. A negated condition is marked in red. A condition the card does not recognise renders nothing at all rather than a guess, and your Condition wording templates replace the default phrases above wherever you set one.
An inventory line states your bound
An Inventory line prints your bound, never a live stock count. That condition is resolved by the app before checkout, per variant, so the card is explaining the rule rather than reporting today’s shelf. See Conditions & Rules for what that means when your stock moves during the day.
A name reaches the storefront when its product syncs
A discount saved before this version shows its tile without a name line until it is saved again, or until the daily sweep resyncs it.
Finally, on the last day of a discount that has an end date, the tile shows Ends today above its countdown.
The price after the discount
Above the tiles, the card shows the selected variant’s price struck through and the price checkout will charge for it, for example €119.00 €89.25. It is formatted by your theme’s own money format, and it changes as soon as the shopper picks another variant.
The card only prints a price it is sure of: the price of one unit added to the cart now, with the discount checkout applies to that variant. A percentage is taken off the variant’s price, and the amount taken off is rounded down to the cent, exactly as checkout rounds it. A fixed amount is taken off in full, and the price never goes below zero.
The variant gets no price at all when:
- the discount checkout applies to it has an Item quantity or Cart value condition. The rest of the cart decides those, so no single price is true. The tile and its window still say what the offer needs. Inventory conditions are fine, because the app resolves them before checkout.
- that discount is a Buy X get Y or Free shipping discount. Neither changes the price of the item itself.
- the variant earns a Buy X get Y gift with Combine with item discounts unticked. Once the shopper adds the gift, checkout may give the gift instead of the variant’s own discount, so its price is not sure.
- that discount is a fixed amount and the shopper is on a market in another currency. Checkout converts your amount with an exchange rate your theme cannot see.
- that discount has volume tiers that start above one item. Its steps are still priced, see below.
- the shopper’s currency has no cents or has three decimal places, such as the Japanese yen or the Kuwaiti dinar.
- the product has subscription options or is a gift card, or the shopper is a B2B buyer whose price changes with the quantity.
- a date or a value on the discount cannot be read, or the discount would not lower the price.
- no live discount covers the variant, for example one narrowed to other variants or skipping it on stock.
When more than one discount reaches the variant, the card picks the one checkout would give one unit added now, by your store’s choice under Settings → Overlapping discounts: the biggest discount, the product’s own discount first, or your priority order. It never falls back to another discount. If a discount that waits on the cart (an Item quantity or Cart value condition, or steps that start above one item) could beat the one shown under that choice, the variant gets no price. A lower price would be wrong the moment the shopper met that condition, because checkout would then apply the other discount.
Untick Show the price after discount in the theme editor to hide every price. The tiles stay exactly as they are.
Volume tiers
A percentage or fixed amount discount can give more per item as the shopper buys more. Its tile reads Up to the best step, for example Up to 15% off, and stays that short. A shopper who clicks it sees a Buy more, save more table in the window, one row per step:
| Quantity | Discount | Price per item |
|---|---|---|
| From 2 items | 10% off | €107.10 each |
| From 3 items, Best value | 15% off | €101.15 each |
The step with the largest discount is tagged Best value. The discount is shown in the colour of your tiles.
The step that applies is the highest one the cart reaches. With All items together, every item in the cart that the discount covers counts, across all the products it applies to. With Per product the rows read From 3 of this product, and with Per variant they read From 3 of the same item, because only those items count. Below the first step the discount applies nothing.
When the card can price the selected variant (see the list above), each step also shows its price per item, for example €101.15 each, and it follows the variant the shopper picks. Checkout takes the discount off each item and rounds the amount down to the cent, so the price per item is the same at any quantity and matches what checkout charges.
The Conditions section follows the table only when there is something to say. An offer whose first step is two items or more never claims No special conditions required. Fixed amounts in the steps follow the currency rule below.
If the steps saved on a discount cannot be used, checkout applies nothing for that discount, and the card shows no tile for it either. The admin and the AI tools refuse such steps, so this only happens to a discount written some other way.
Collection and all-products offers
A discount that applies to Collections or All products shows on the product page too. An all-products offer appears on every product, and a collection offer on the products of its collections. The card follows the same choice as checkout, the one under Settings → Overlapping discounts, so the price a shopper is shown is the price they are charged.
Products a discount leaves out
A product a collection or all-products discount leaves out under Exclusions, by itself or through a collection it is in, is left out on the storefront too: the offer card shows no tile for that discount on it, the discount badges do not name that discount on it, and the cart progress bar does not count it toward that discount or promise it anything. Checkout leaves it out the same way.
When a discount leaves out a collection that is not published to your online store, the storefront cannot tell which products are in it. That discount then shows no tile and no badge on any product it reaches, and the bar does not name it, although checkout still applies it to every product outside that collection. See Leaving Products Out.
Only the offers the product can get
Only one percentage or fixed amount discount applies per item, so the card does not show two such tiles where only one can ever apply. A tile is left out when another discount always beats it on this product. That other discount applies from a single item with no Item quantity or Cart value condition, is running today, covers every variant the left-out one covers, and wins under your store’s choice:
| Your choice | The other discount always beats it when |
|---|---|
| Biggest discount wins | It takes at least as much off one item as the left-out discount’s best step could, at every variant price of the product |
| The product’s own discount first | It comes first: set on the product before a collection one, a collection one before an all-products one, then the lower priority number |
| My priority order | It has the lower priority number |
So with a 12% collection sale and a 5% all-products sale on the same shirt, under Biggest discount wins the shirt shows the 12% tile only. A discount that waits on the cart keeps its tile, because the cart decides whether it wins. Buy X get Y and Free shipping tiles always show, because neither takes an item’s place. A Cart spend discount without Also discount items that already have a discount is not shown on a product that already has an item discount on every variant from the first item, because checkout never takes the cart spend discount off that product.
A collection offer only shows on a product whose collection is published to your online store. A collection you keep unpublished gets no tile, although checkout still applies the discount to its products. Because checkout can still pick that hidden discount, the card shows no price after discount on a variant it might win, rather than a price checkout would not charge.
Offers kept for some customers
A discount whose Who can get it is not Everyone shows only to the shoppers who can get it, on the offer card, on the badges and in the cart progress bar alike. A VIP offer, one for Customers tagged VIP, shows to a customer tagged VIP who is logged in to their account, and to no one else. A B2B buyer never sees a retail-only offer, and a retail shopper never sees a B2B-only one. An offer for In store only never shows online, and an offer for chosen companies shows only to a buyer buying for one of them. A guest never sees a VIP offer or a VIP price, and sees the offers for everyone as before. An offer for some Countries shows only to shoppers browsing your store in one of them. Checkout follows the same rules, so a shopper is never shown an offer that checkout would refuse them. See Who Can Get It.
One offer or every offer
What the card shows is your choice, under Settings → Storefront features → Product page offers:
| Choice | What the card shows |
|---|---|
| One offer | A single tile: the first kind of offer in your order that the selected variant can get. Every store starts here |
| Every offer it can get | A tile for each offer the product can get |
With One offer, the order you set under When showing one offer, show first decides which kind of offer the tile is. There are four kinds:
| Kind | What it covers |
|---|---|
| Item discount | A percentage or fixed amount off the item, with or without volume steps, like 5% off |
| Gift offer | A Buy X get Y discount, like a free gift with a purchase |
| Cart spend offer | A cart spend discount, like 10% off orders over $100 |
| Free shipping | A free shipping discount |
Every store starts with them in that order: Item discount, Gift offer, Cart spend offer, Free shipping. The card first leaves out every offer the product can never get, as Only the offers the product can get explains above. Then it walks down your order and shows the first kind the product still has an offer of. When the product has more than one offer of that kind, it shows the one checkout would give first. For item discounts, that is the one checkout gives one unit added now, under your Overlapping discounts choice. For the other kinds, it is the first one under that same choice.
The tile follows the selected variant. An offer kept for some of a product’s variants is the tile only on those variants. On the others the card shows the next offer in your order that the variant can get, and it changes tile as soon as the shopper picks another variant. For example, with Gift offer first and a gift offer for buying the Special variant only, the Special variant shows the gift, and the other variants show the item discount they get, with their price. When no offer reaches the selected variant at all, the card shows the first one in your order, marked as not for the chosen variant.
An example. A snowboard has three live offers: a free wax with every board (a gift offer), 5% off all products (an item discount) and 10% off orders over $100 (a cart spend offer). With One offer and the order every store starts with, the snowboard’s card shows one tile, 5% off. Move Gift offer above Item discount and the same card shows the free wax instead. Choose Every offer it can get and it shows a tile for each offer the snowboard can get.
The price after the discount shows whatever the tile is. With One offer, the card prints the same price as with Every offer it can get: the price checkout charges for the selected variant, as The price after the discount describes above. So when the one tile is a gift, a cart spend offer or free shipping and the variant also gets an item discount, the shopper still sees the price they will pay. For example, with Gift offer first, the Special variant that earns a free wax shows the gift tile and, above it, its own price after its 30% off.
Discount badges follow the same choice. With One offer, a product’s badge on your collection and search pages names the same offer its card shows, picked by the same order. A badge stands for the whole product, so a product’s own offer kept for some of its variants can name the badge, while the card shows that offer on those variants only. With Every offer it can get, the badge works as described in What a badge says, below.
When the Card Shows Nothing
The card renders nothing, so no empty box, no heading, not even its stylesheet, unless a product has at least one live offer to show. That means no card when:
- the product is not targeted by any discount
- every discount on the product is Draft or Archived
- today falls outside every discount’s Discount period
- the block is not on your live theme.
Collection and all-products discounts count for the first case too. A product with no discount of its own still gets a card when one of those reaches it.
The card also shows nothing on a gift card, which Shopify never discounts, or on a product that can only be bought on a subscription, because xDiscount discounts one-time purchases only. No offer is shown where checkout cannot give one.
A Discount code never shows on the card, live or not. A code is something you hand out, and the card cannot know whether a shopper has it. Your automatic discounts on the same product still show.
Both period dates are inclusive whole days in your store’s timezone, and each side works independently. A start date with no end date runs forever, and a discount whose start and end are the same date runs for that one day.
An unreadable date is treated differently here
If a date on a discount is unreadable for any reason, the card treats it as not set and keeps showing the offer, while checkout does the opposite and stops applying it. That asymmetry is on purpose. A card that shows too often is visible and you can fix it, while a discount that wrongly applies costs you money on every order.
The card follows the variant the shopper selects. A discount narrowed to specific variants says Applies to selected variants only in its details while the selected variant is one of them. The moment the shopper picks a variant you left out, that offer is dimmed and flagged Not available for the selected variant, and it comes back when they pick one you included. A whole-product discount that skips out-of-stock variants, or carries an Inventory condition, does the same on the variants it skips, and the stock line follows too.
The card reads the selected variant the way every theme announces it, through the page’s URL and the product form, so what a shopper sees on the tile is what checkout will do for the variant in their hands.
The Gift Picker, Buy X Get Y
On a Buy X get Y discount, the tile carries a button reading Choose your free gift, or whatever you typed into Gift picker label. It opens the gift window.
What shoppers see in the window. One row per gift product you picked, each with the product’s title, a small image where we have one, and an Add button. A gift with no title falls back to Free gift. Under the list, a line reads 0 of 2 selected, counting against the Number of gift items you set on the discount.
A gift with more than one variant to choose from reads Choose instead of Add: clicking it expands the variants, each named as your store names them (Small, Large) with an Add of its own, and a sold-out variant is greyed out as Sold out. Variant names and availability are read from your store’s own product data when the window opens, so they are always current and never stored on the discount.
What happens on Add. One unit of that gift is added to the cart, marked as a gift line, the row changes to Added, and the count goes up by one. A shopper who wants two of the same gift clicks Add twice, and one who wants one of each clicks each once. Your discount then takes the percentage you set off that line at checkout, for at most that many units across the whole cart. Once the count reaches the limit, every Add button greys out, because a further gift would be charged in full at checkout. A button is also greyed out while its request is in flight and comes back when it finishes, so a shopper who hit a failure can try again.
Things worth knowing:
- The marker the card puts on the cart line says only “this line is a gift”. Every value, so the percentage, how many gifts are covered, the schedule and the conditions, still comes from your discount. A shopper’s browser can never decide what a gift costs.
- Which variants a gift offers is your call in the picker: tick the product whole and every variant is offered, or open it and tick specific variants to limit the choice. Checkout only ever discounts a gift variant you allowed, whatever a shopper’s browser claims. A gift saved before this option existed offers the one variant captured at the time. Open the picker and reselect it to offer more. A gift we have no variant for at all is skipped, and the whole gift area is hidden if that leaves nothing to choose.
- After the gift is added, the card tells your theme to refresh its own cart. Most themes pick this up. If yours does not update its cart drawer, the item is still in the cart, and a page refresh will show it.
- A Buy X get Y discount with no gift products cannot be saved as Active at all, and the discount form warns: “No gift chosen yet. Shoppers cannot claim this offer until you pick one.”
Why Amounts Show in Your Store’s Currency
This is the question merchants ask most about the card, so here is the straight answer.
Fixed amounts are stored in your store’s currency, because that is the currency you typed them in. At checkout, Shopify converts that figure to the shopper’s currency using the real exchange rate for their market.
The card, running in your theme, has no access to that exchange rate. Shopify’s theme templates expose a currency’s code, name and symbol, never the rate. So if the card simply formatted your number with the shopper’s currency symbol, a shopper in a euro market would read “€10.00 off” while checkout took about €9.20. The card and checkout would disagree, which is exactly what this app is built to prevent.
The rule the card follows: format the amount normally unless a mismatch is possible.
| Situation | What the card prints |
|---|---|
| The shopper’s currency and your store’s currency are the same | $10.00 off, your theme’s normal money formatting |
| The shopper is on a market with a different currency, or we cannot read theirs | 10 EUR off, your own figure, with your store’s currency code stated |
The same rule applies to Cart value conditions, so a threshold never tells a shopper to spend the wrong amount to qualify.
It applies to fixed amounts in volume steps too, and the price after the discount goes further: on a market in another currency, a fixed amount is never priced at all.
Percentages are never affected, because 20% off is 20% off in every currency, and neither is free shipping. The caution costs you nothing except on the amounts where being wrong would actually matter.
Selling in one currency only
You will never see the second form. It appears only on multi-currency markets, and what it shows is true on every one of them: checkout converts your figure for the shopper.
Discount Badges on Collection Pages
The offer card lives on your product pages. Discount badges bring the offer to your collection pages and search results: a small label on the corner of a product’s image, such as 20% off, so shoppers see it while they browse.
Switching the badges on
Discount badges are an app embed, not a block you place on a template. Shopify keeps them off until you switch them on, and xDiscount takes you straight to the switch.
Open Storefront features
In xDiscount, go to Settings → Storefront features.
Click Turn on
On the Discount badges on collection and search pages card, click Turn on. Your theme editor opens in a new tab on App embeds, on a collection page, with Discount badges already switched on.
Save in the theme editor
Click Save in the theme editor.
Go back to xDiscount
The card’s badge changes to On by itself within a few seconds. If it has not, click Check again.
To do it by hand instead: in Shopify, go to Online Store > Themes, click Customize on your live theme, open App embeds in the left sidebar, switch on Discount badges and click Save. To switch them off later, click Open theme editor on the same card and turn them off there.
The embed only runs on collection pages and search results, and adds nothing to your other pages. Its small script and stylesheet load only on a page where at least one product has a badge.
What a badge says
A product gets one badge at most. With One offer under Product page offers (every store starts there), the badge names the same offer the product’s card shows, picked by the same order, as One offer or every offer explains. With Every offer it can get, it names the offer the product gets under your store’s choice in Settings → Overlapping discounts, the same choice checkout follows:
- Biggest discount wins: the discount that takes the most off the product.
- The product’s own discount first: a discount on the product itself, then one on a collection the product is in, then one on all products. Between two of the same kind, the lower priority number.
- My priority order: the discount with the lowest priority number.
| Discount | What the badge says |
|---|---|
| Percentage | 20% off |
| Fixed amount | $5.00 off, or 5 USD off on a market in another currency, the same rule as the offer card |
| Percentage or fixed amount with volume tiers | Up to 15% off |
| Buy X get Y | Free gift, or 50% off a gift |
| Free shipping | Free shipping |
The wording is exactly the wording of the offer card’s tile for the same discount.
A badge never shows a price. It says what the offer is, never what the product will cost, because the price at checkout can depend on the cart, the quantity and the shopper’s currency. The offer card on the product page lists the offer’s conditions.
A badge only appears for a discount that is Active and inside its Discount period today, in your store’s timezone. A discount with a date the app cannot read gets no badge, because checkout does not apply it either.
A badge only names a discount the shopper can get. A VIP offer gets a badge for a logged-in customer tagged VIP and none for a guest, as Offers kept for some customers explains.
No badge on a gift card or a subscription-only product. Shopify never discounts a gift card, and xDiscount discounts one-time purchases only, so a product that can only be bought on a subscription gets no badge either. The offer card leaves both out too.
Badge settings
The badge is designed in xDiscount, not in the theme editor: the Discount badges embed has no settings of its own. Go to Settings → Storefront features and use Badge design, inside the Discount badges on collection and search pages card.
| Setting | Default | What it does |
|---|---|---|
| Style | Pill | The shape of the badge: Pill, Rectangle, Corner ribbon, Circle or Tag. The corner ribbon is a band across the corner of the image |
| Corner | Top right | The corner of the product image the badge sits in: Top left, Top right, Bottom left or Bottom right |
| Size | Medium | Small, medium or large |
| Background colour | Violet, #8b5cf6 | The colour the badge is filled with, the offer card’s own default |
| Text colour | White, #ffffff | The colour of the words on the badge |
| Badge text | {value} | Up to 30 characters. {value} is replaced by the offer, so Save {value} shows Save 20% off. Text without {value} shows as it is on every badge. Spaces in a row show as one |
A preview shows the badge on a product image as you go, drawn the way your store draws it, and Save puts it on your store. Every store starts with a violet pill in the top right corner, medium sized, with white words that name the offer, such as 20% off.
The badge steps aside for your theme’s own labels. Many themes print their own label on a product image, such as Sold out or Sale. When the corner you chose already holds one, the badge moves just below it in a top corner, or just above it in a bottom corner, so both stay readable. It never covers your theme’s label. The badge starts in the top right because most themes put their labels in the top left.
Every kind of offer gets a badge: percentage and fixed amounts, gifts and free shipping. There is no switch to leave a kind out.
Known limits
- Badges appear on collection pages and search results only. Product recommendations, a featured collection on your home page and other product lists show none.
- A product the page cannot read shows no badge, never a guessed one. The embed reads at most 50 products of the page Shopify renders. Depending on how your theme splits a long collection into pages, products further down can be left without a badge, and so can products your theme adds while the shopper scrolls.
- When a shopper filters or sorts, the badges come back on the cards your theme redraws, for the products the page read when it loaded.
- A discount on a collection that is not published to your online store is invisible to the page, because your store does not list that collection for its products. Checkout still applies it, so wherever it could come first, the page shows no badge rather than one checkout might not honour. In practice, while you run such a discount, products that could be in that collection show no all-products badge, and no badge for a collection offer it would come before. The app saves each collection’s handle with the discount so the page can confirm a collection is published. A collection whose handle the app could not record counts as possibly unpublished.
- Your theme decides how a product card is built. The badges find a card by its link to the product and its image, which works on Shopify’s own themes such as Dawn and Horizon. A card built some other way can be left without a badge.
Cart Progress Bar and Automatic Gift
The cart progress bar tells shoppers how close their cart is to your next cart offer, right where they look before checking out: Spend $40.00 more to get 10% off your order, then You unlocked 10% off your order once they get there. The same embed can also put a free gift in the cart on its own when the cart qualifies for it.
Switching the bar on
The bar is an app embed, so Shopify keeps it off until you switch it on, and xDiscount takes you straight to the switch.
Open Storefront features
In xDiscount, go to Settings → Storefront features.
Click Turn on
On the Cart progress bar and automatic gift card, click Turn on. Your theme editor opens in a new tab on App embeds, with Cart progress bar already switched on.
Save in the theme editor
Click Save in the theme editor.
Go back to xDiscount
The card’s badge changes to On by itself within a few seconds. If it has not, click Check again.
To do it by hand instead: in Shopify, go to Online Store > Themes, click Customize on your live theme, open App embeds in the left sidebar, switch on Cart progress bar and click Save. The automatic gift needs this switch on too.
The embed runs on every page, but it adds nothing to a page until one of the offers below is live. Its small script and stylesheet load only then.
What the bar says
| Offer | What the bar says |
|---|---|
| Cart spend discount, percentage | Spend $40.00 more to get 10% off your order, then You unlocked 10% off your order |
| Cart spend discount, fixed amount | Spend $40.00 more to get $10.00 off your order |
| Free shipping with a cart value minimum | Spend $20.00 more to get free shipping, then You unlocked free shipping |
| Buy X get Y with a cart value minimum | Spend $25.00 more to get a free gift, or 50% off a gift for a partial gift |
The bar shows one message: the offer the cart is closest to reaching. Once every offer is reached, it names the one with the highest threshold. A step of a cart spend discount that is already passed is not mentioned again.
The bar never shows a total. It names the amount still to spend and the offer, nothing else. It measures the cart the way checkout does:
- Free shipping and gifts count your prices before any discount, exactly as checkout reads a cart value condition.
- Cart spend discounts count prices after item discounts, as checkout does. When Shopify leaves an item discount out because the cart spend discount saves the shopper more, the bar counts the price without it, as your cart shows it.
- Gift items, and items sold by another shop in the same cart, are left out, as checkout leaves them out.
- On a market in another currency, your amounts are converted with the shopper’s exchange rate and the amount to spend is rounded up to the cent, so spending exactly what the bar says always reaches the offer. In a currency without cents, such as the Japanese yen, the bar stays hidden, the same rule as the offer card’s prices.
The bar says You unlocked only when checkout will give it, and a fixed amount only when the items it applies to cover it. A cart spend discount without Also discount items that already have a discount is not shown at all while every item in the cart already has a discount, because checkout gives it nothing then. When only some items have one, the bar says 15% off items not already discounted, as checkout takes the percentage off the other items only. When the cart spend discount leaves some products out (see Leaving Products Out), those items do not count toward its steps, and the bar says 15% off eligible items.
Which offers the bar follows
- Offers that are Active and inside their Discount period today, in your store’s timezone. A date the app cannot read hides the offer, because checkout does not apply it either.
- Discounts on All products or on Collections. A collection offer counts only once the cart holds an item the page saw in one of its collections. An item added since the page loaded counts from the next page load.
- Free shipping and Buy X get Y discounts whose only condition is a minimum cart value. Any other condition, a maximum, or Negate this condition keeps the offer out of the bar, because the bar cannot say what it would take.
- Only offers the shopper can get. A VIP offer counts for a logged-in customer tagged VIP and is left out of the bar for everyone else, as Offers kept for some customers explains.
- Cart spend discounts with no other condition. Only one can be active at a time. A store that had two live before that rule keeps them until one is archived or set to Draft, and until then the bar names neither: checkout gives the larger of the two, and which one that is depends on the cart.
Nothing shows on an empty cart.
Bar settings
The bar is designed in xDiscount, not in the theme editor: the Cart progress bar embed has no settings of its own. Go to Settings, then Storefront features, and use Bar design, inside the Cart progress bar and automatic gift card.
| Setting | Default | What it does |
|---|---|---|
| Placement | Automatic | Automatic puts the bar at the top of your cart drawer or cart page when your theme has one, and in a slim bar at the top of the page otherwise. Cart drawer and cart page only never shows the slim bar. Top of the page always uses it |
| Style | Card | Card is a rounded box. Strip is flat and runs the full width. Pill has fully rounded ends. Minimal shows only the words, in your theme’s own text colour, and the progress line. Milestones is a rounded box that also shows every step of the offer under the line, as Milestones below explains |
| Line thickness | Medium | How thick the progress line is: Thin, Medium or Thick |
| Alignment | Left | Where the words sit in the bar: Left or Centre |
| Show an icon before the words | No icon | A small icon before the words, in their colour: a gift for a gift offer, a truck for free shipping and a tag for a cart spend discount |
| Progress colour | Violet, #8b5cf6 | The line that fills as the cart gets closer to the next offer |
| Background colour | Pale violet, #f5f3ff | Behind the wording and the progress line. Minimal has no box, so there it is the colour behind the progress line |
| Text colour | Near black, #1f2937 | The wording. Minimal has no box to read it on, so it uses your theme’s own text colour instead |
| Wording before an offer is reached | (empty) | Up to 80 characters. Use {amount} and {offer} where they go, for example Only {amount} away from {offer}!. Empty uses Spend {amount} more to get {offer}, in each shopper’s language. Wording without both is not saved |
| Wording once an offer is reached | (empty) | Up to 80 characters. Use {offer} where the offer goes, for example {offer} is yours!. Empty uses You unlocked {offer}, in each shopper’s language. Wording without it is not saved |
A preview shows a cart with your bar in it as you go, before the offer is reached and once it is, drawn the way your store draws it, and Save puts it on your store. Every store starts with a pale violet card at the top of the cart drawer, a violet line of medium thickness, no icon, and near black words on the left in the shopper’s language. Your own wording shows as you typed it, in every language.
Milestones
With Milestones, the bar also shows the steps of the offers it follows, under the progress line: one dot per step, with its icon inside when Show an icon before the words is ticked, and the offer in words under it. A step the cart has reached is filled with your progress colour. The words above the line are the same as in every other style.
- The steps are the tiers of your cart spend discount, your free shipping threshold and your gift offers, in order of the amount. Free shipping is one step: the lowest threshold, or the one the words name.
- Only steps measured the same way share the line. Cart spend tiers count the cart after item discounts, while free shipping and gifts count it before them. So when the cart holds a discounted item, the bar shows only the steps measured like the offer the words name, and the line is never filled on one measure for a step checkout measures on another.
- Steps at the same amount share one dot, their offers joined with a plus sign.
- At most four steps show: the one the words name, one below it and the rest above.
- The line is cut into equal parts, one per step, with each dot under the end of its part. Each part fills as the cart moves from the step before to its own.
- A step checkout would not give in full is never shown as reached, for example a fixed amount larger than what it can take off the cart.
The automatic gift
A Buy X get Y discount with Add the gift to the cart automatically ticked puts its gift in the cart by itself instead of waiting for the shopper to pick it from the offer card. The cart progress bar must be switched on for this, because the bar’s script is what adds the gift. The offer card then shows no gift picker for it, only “Your free gift is added to your cart automatically”, so shoppers know they don’t have to click anything. If the bar is switched off, or the shopper removed the gift from their cart, the card shows the picker instead, so the gift can always be had. The rule:
- Only a gift that is 100% off. Anything less would raise the shopper’s total without their say, which Shopify does not allow an app to do.
- The gift is added once the cart holds an item the discount covers, meaning one of its products, an item in its collections, or any item, and meets its condition the way checkout does: no condition, a minimum quantity of items in the cart, or a minimum cart value. A discount with any other condition keeps the gift button on the offer card instead. For a discount on specific products, the bar knows the products in the cart when the page loads and the product of the page the shopper is on, so a product added from a quick add on a collection page brings its gift on the next page, the cart page included. The first gift in your list that is in stock is added, as its default variant, one unit, marked as a gift line exactly as the offer card marks one.
- Nothing is added while the discount is not Active or is outside its Discount period, when the shopper already took one of its gifts from the offer card, or in a currency where the bar stays hidden.
- If the cart stops qualifying, the gift is taken back out, for example when the shopper removes the product that brought it or the cart drops below the minimum. Only a gift the bar added itself is ever removed. A gift the shopper added from the offer card is never touched.
- If the shopper removes the gift, it is never added again in that cart. The cart records it in the private cart attribute
__xd_gift_declined, which you can see on the order in your admin. A new cart starts afresh. - After adding the gift, the bar checks that checkout makes it free. If it does not, for example because another discount claims that gift first, the gift is taken back out, is not added again in that cart, and the bar stops naming it.
The gift is a real item in the cart
If your shipping rates depend on weight, or the rest of the cart needs no shipping, set the gift product up so it does not change the shipping a shopper pays.
Known limits
- The bar finds your cart drawer or cart page by its cart form, the way Shopify’s Dawn theme and most others build them. On a theme built some other way, Automatic falls back to the slim bar at the top.
- After the bar adds or removes a gift, it asks your theme to redraw its cart. Shopify’s current themes, such as Horizon and Heritage, redraw it at once through Shopify’s standard cart events, and so do most other themes. If yours does not, the change is in the cart and shows after the next page load.
- The bar remembers a declined gift in the shopper’s browser. A browser that blocks site storage gets the bar but no automatic gift, because the bar could not keep its promise not to add a declined gift again.
Languages
The offer card, the discount badges and the cart progress bar show in your shoppers’ language. Every word xDiscount writes itself, from 20% off and Click to see details to the condition wording, the countdown units, the gift picker and the bar’s messages, ships in English and in the 20 languages of the Shopify admin:
Chinese (Simplified), Chinese (Traditional), Czech, Danish, Dutch, Finnish, French, German, Italian, Japanese, Korean, Norwegian (Bokmål), Polish, Portuguese (Brazil), Portuguese (Portugal), Spanish, Swedish, Thai, Turkish and Vietnamese.
There is nothing to switch on. Shopify picks the language from the storefront the shopper is on. On your French storefront the tile reads 20 % de réduction and Voir les détails, on your German one 20 % Rabatt and Details ansehen, and on your Japanese one 20%OFF and 詳細を見る. The theme editor’s labels and help text for the three of them follow the language of your Shopify admin, in the same languages.
What you type shows as you typed it. Your theme editor wording, such as Details line, Gift picker label, Stock wording, the six Condition wording templates and the bar’s two wordings, is shown to every shopper exactly as you wrote it, whatever the storefront’s language. So are each discount’s name and the Badge text you set in xDiscount. Leave a wording setting empty and each shopper gets the default in their own language, which is usually the better choice for a store that sells in more than one language.
App wording is not editable
Shopify does not let a store edit the wording an app ships, in any language. To say something your own way, type it into the matching theme editor setting.