F12 Labs
DiscountlyDiscountly documentation / Theme blocks
Cart embed
How Discountly's cart embed adds free gifts and Buy X get Y rewards to the cart, every setting in the theme editor with its default, upsell progress bars, and the reset link for gifts a shopper removed.
The Discountly Cart Embed is an app embed: one switch in the theme editor that runs on every page of your store. It's what puts free gifts and Buy X get Y rewards into the cart. It can also show a short notification when that happens, and progress bars in the cart such as "Add $12.00 more to get free shipping".
If you haven't turned it on yet, Store setup and theme blocks shows how.
When you need it
You need the cart embed if you have a live automatic discount of one of these types:
- Free gift with purchase
- Buy X get Y
Shopify's discounts make an item free, but they don't add it to the cart. The embed does that part. Without it, the discount is live but the gift never appears, so the shopper only gets it by adding it themselves.
Volume, product, order and shipping discounts don't need the embed. Shopify applies them at checkout on its own. You only need it for those if you want upsell hints in the cart.
What it does in the cart
Each time the cart changes, the embed checks it against your live automatic gift and Buy X get Y discounts:
- Adds the reward when the cart qualifies. Shopify then prices it at $0.00 in the cart and at checkout.
- Removes it when the cart stops qualifying, for example when the shopper takes out an item and drops below the minimum.
- Keeps the quantity right. A shopper can't raise the quantity of a free item. With incremental Buy X get Y rewards, the free quantity follows what they bought: buy 2 get 1 becomes buy 4 get 2.
- Uses your backup gift when the main one is out of stock, if the discount has one. If both are out of stock, nothing is added.
- Refreshes your theme's cart drawer so the shopper sees the gift without reloading the page.
When a shopper removes the gift
If a shopper deletes a free item from their cart, the embed remembers that and doesn't add it back. Shoppers who say "no thanks" aren't fighting the cart.
That choice is saved with the cart, so it lasts until the cart is cleared, for example after an order is placed. To always put gifts back, turn on Re-add items after manual removal (see Settings). For one shopper who changed their mind, use the reset link.
Settings
Open Online Store → Themes → Customize, then App embeds, and expand Discountly Cart Embed. The settings are in five groups.
Auto-add behavior
| Setting | Default | What it does |
|---|---|---|
| Max Retries | 3 | How many times the embed tries to add a reward before giving up, for example when Shopify refuses because of stock |
| Re-add items after manual removal | Off | When on, gifts a shopper removed are added back on the next cart change |
Customer support
| Setting | Default | What it does |
|---|---|---|
| Reset link parameter | reset_free_rewards |
The word in the reset link. Change it only if it clashes with another app |
Free gift notification
A small message on the page when the embed adds a gift, or removes one that no longer qualifies. It doesn't appear when a shopper removes a gift themselves.
| Setting | Default |
|---|---|
| Show a notification when a free gift is added or removed | Off |
| Added message | A free gift was added to your cart. |
| Removed message | A free gift was removed from your cart. |
| Position | Top right. Also top left, top center, bottom right, bottom left, bottom center |
| Background color | #4CAF50 (green) |
| Text color | #FFFFFF (white) |
| Duration | 4 seconds (1 to 15) |
Upsell hints
| Setting | Default | What it does |
|---|---|---|
| Show upsell hints | Off | Shows a progress bar in the cart drawer and on the cart page |
| Position in cart | Top of cart | Or Bottom of cart |
| Custom container selector (advanced) | Blank | A CSS selector for where the bar goes. Leave blank to find the cart automatically |
| Bar fill color | #4CAF50 | |
| Bar track color | #e3e3e3 | |
| Text color | #1a1a1a |
See Upsell hints for which discounts show a bar and how to word it.
Developer
| Setting | Default | What it does |
|---|---|---|
| Verbose console logging | Off | Writes every check and cart change to the browser console. Turn it on while troubleshooting, then off again |
Click Save in the theme editor after changing anything.
Upsell hints
Upsell hints are progress bars that tell shoppers how close they are to a deal, such as "Add $12.00 more to get Free shipping" or "Add 2 more for 15% off". When the cart qualifies, the bar can say so: "You've unlocked Free shipping!"
Two switches control them:
- In the theme: turn on Show upsell hints in the cart embed settings.
- In each discount: open the discount in Discountly, click Advanced settings, and under Upsell hints → In the cart, choose when the bar appears.
| Discount setting | Default | What it does |
|---|---|---|
| Show from | 50% | How far toward the goal the cart must be before the bar appears. At 50%, a $100 free shipping goal shows from $50 |
| Hint message (optional) | Blank | Your own wording, up to 150 characters. Blank uses Discountly's message |
| Unlocked message (optional) | Blank | Shown when the cart qualifies. Placeholder: "You've unlocked {reward}!" |
You can use these tokens in the messages:
| Token | Becomes |
|---|---|
{remaining} |
What's left to add, such as $12.00 or 2 items |
{product} |
The products that count toward the goal |
{reward} |
What the shopper gets, such as Free shipping or 15% off |
{code} |
The discount code, for code discounts |
Volume, Buy X get Y, free gift and shipping discounts can show hints. Product and order discounts can too, as long as they have a minimum requirement or a shipping add-on, since otherwise there's no goal to reach.
The cart shows one bar at a time: the discount the shopper is closest to unlocking.
The reset link
When a shopper removed a gift and then wants it back, send them a link to your store with the reset parameter:
https://your-store.com/?reset_free_rewards=1
Opening it clears the gifts they removed, and any gift their cart still qualifies for is added again. The parameter is taken out of the address bar straight away, so a refresh or bookmark doesn't reset again. It works on any page of your store, not just the home page.
If you changed Reset link parameter, use your word instead of reset_free_rewards.
How quickly changes reach the storefront
The embed reads your live gift and Buy X get Y discounts from a short cache, so a discount you've just saved or turned off can take up to a minute to show in carts. You can change this in Discountly under Settings → Storefront performance → Rules cache duration, from 5 seconds to 5 minutes. One minute is recommended.
Troubleshooting
The gift isn't added. Check, in order:
- Store setup shows Cart embed: On, and you saved the theme editor.
- The discount is live, automatic, and inside its schedule.
- The cart meets the minimum, counting only the products the discount counts.
- The shopper is eligible, if the discount is limited to logged-in, tagged or specific customers.
- The gift (or backup gift) is in stock and available on the Online Store.
- The shopper didn't remove it earlier. Send them the reset link, or try in a private window.
The gift was added but the cart drawer didn't update. Most themes refresh on their own. If yours doesn't, the gift shows after reloading the page. Email support@ftwelvelabs.com with your theme's name so we can add support for it.
The upsell bar doesn't appear. Check that your store is on Pro, that Show upsell hints is on in the embed, and that the cart has reached the discount's Show from percentage. If your cart drawer is custom, enter its CSS selector in Custom container selector.
I need to see what the embed is doing. Turn on Verbose console logging, open your store, and watch the browser console while you change the cart. Turn it off when you're done.