Auto-add a free gift at a threshold

Watch the cart total and keep a free gift in sync with it: add the gift once the shopper crosses a spend threshold, remove it if they drop back below.

For a merchant-configured version with tiers, per-market rules, and a progress bar, use the Rewards block, with no code. This is for when your rule is something the block can’t express.

The snippet

Paste into Cart settings → Custom script → Initialization, and set the two constants:

const FREE_GIFT_VARIANT_ID = 1234567890; // the gift product's variant id
const THRESHOLD_CENTS = 5000;            // $50.00, since totals are in cents

function reconcileGift(state) {
  const gift = state.items.find((line) => line.variantId === FREE_GIFT_VARIANT_ID);
  const qualifies = state.totalPrice >= THRESHOLD_CENTS;

  if (qualifies && !gift) {
    window.aftersell.cart.actions.addItem(FREE_GIFT_VARIANT_ID, 1);
  } else if (!qualifies && gift) {
    window.aftersell.cart.actions.removeItem(gift.key);
  }
}

window.aftersell.cart.events.on('cart_loaded', reconcileGift);
window.aftersell.cart.events.on('cart_updated', reconcileGift);

How it works

reconcileGift describes the state the cart should be in, then makes at most one change to get there:

Qualifies and the gift isn’t there → addItem adds it.
Doesn’t qualify and the gift is there → removeItem removes it, by the line’s key.
Otherwise → do nothing.

It runs on both cart_loaded (so a cart that already qualifies on page load gets the gift) and cart_updated (so it reacts to every change afterward). Because cart_loaded replays to late subscribers, this works no matter when your script runs.

The !gift / gift guards are what stop this looping. Adding the gift fires cart_updated, which runs reconcileGift again, and the second pass finds the gift already present, so it does nothing. Strip the guards and you get an infinite loop. See the two rules.

Note that adding the gift raises the cart total, so a threshold near a product’s price can oscillate: adding a $0 gift is safe, but a gift with a price could push the cart above the threshold on its own. Keep the gift free, or compare against a total that excludes it.

Adapting it

Gate on item count instead of spend:

const qualifies = state.itemCount >= 3;

Gate on a specific product being in the cart:

const qualifies = state.items.some((line) => line.productId === TRIGGER_PRODUCT_ID);

Only in certain countries. Read context, which is available before the cart loads:

const ELIGIBLE = ['US', 'CA'];

// Only register the handlers for eligible countries.
if (ELIGIBLE.includes(window.aftersell.cart.context.customer_country)) {
  window.aftersell.cart.events.on('cart_loaded', reconcileGift);
  window.aftersell.cart.events.on('cart_updated', reconcileGift);
}

Exclude the gift from the threshold so it can’t hold itself up:

const subtotalWithoutGift = state.items.reduce(
  (sum, line) => (line.variantId === FREE_GIFT_VARIANT_ID ? sum : sum + line.finalLinePrice),
  0
);
const qualifies = subtotalWithoutGift >= THRESHOLD_CENTS;

Mark the gift so it reads as a gift. A line transform can change a line’s title, variant title, hidden state, and internal properties — so relabel it:

window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.variantId === FREE_GIFT_VARIANT_ID) {
    line.setTitle('Free gift 🎁');
  }
});

A line transform cannot hide a line’s quantity controls — its only setters are setTitle, setVariantTitle, setHidden, and setInternalProperties. If a shopper changes the gift’s quantity, correct it from a cart_updated handler instead.

Where to go next

Rewards block: the no-code version, with tiers.
Actions: addItem, removeItem, and the rest.
Events: why the guards matter.

Getting Started

Home Page

Best Practices

Post-Purchase Upsells

Cart

Checkout Upsells (Shopify Plus)

Thank You Page

Product Page Upsells

Rokt Thanks

Strategies

Analytics & Tracking

Integrations

Aftersell MCP

Billing & Account

Troubleshooting

The snippet

How it works

Adapting it

Where to go next

​The snippet

​How it works

​Adapting it

​Where to go next

The snippet

How it works

Adapting it

Where to go next