Most gift-with-purchase (GWP) setups break for the same reason: someone writes JavaScript that watches the cart and removes the gift by hand when something changes. It works until the customer edits quantities, uses an app’s cart drawer, or the event never fires. The solid approach is to watch nothing: tie the gift to its product as a nested line item and let Shopify remove it with cascade delete.
The problem with a hand-rolled GWP
The usual pattern is a script that listens for cart changes, checks whether the
gift is still earned, and removes it if it isn’t. The catch is that there are a
lot of ways to change a cart on Shopify: the theme’s add to cart, quick add, a
third-party app’s drawer, the /cart page, a quantity update. If your removal
logic doesn’t cover every one of them, sooner or later the gift gets stuck in a
cart where it no longer belongs. And chasing every event is a fight you don’t
win.
The idea: a child line with parent_line_key
/cart/add.js accepts a little-known field: parent_line_key. When you pass
it, the line you add gets nested under another one as a child line. It’s the
same mechanism bundles use. And here’s the part that matters: when the customer
removes the parent line, Shopify cascade deletes the child, without you
writing anything for that removal.
// When you add the gift, hang it off the parent line (the product that triggers it).
await fetch('/cart/add.js', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({
items: [{
id: giftVariantId,
quantity: parentLine.quantity,
parent_line_key: parentLine.key, // <- this makes it a nested line item
properties: { _gift: '1', _gift_for: String(parentLine.variant_id) },
}],
}),
});
parent_line_key points to the parent line’s key. That makes the gift its
child. If the customer removes the product, the gift goes with it through
cascade delete.
JavaScript doesn’t set the $0 price
The gift costs $0 because of a Shopify automatic discount that targets that variant, not because of anything you do on the front end. This matters: the price lives in Shopify, not in the browser. Never touch prices on the client. They can be tampered with, and they break checkout integrity.
What you do have to keep in sync
Shopify gives you cascade delete for free, but the rest is on you. On every
cart change you re-evaluate: for each qualifying product that doesn’t have its
paired gift, you add it; if the parent line’s quantity changed, you adjust the
gift’s. You pair each gift with its parent through a property (_gift_for =
the parent line’s variant id).
const cart = await fetch('/cart.js').then((r) => r.json());
const parents = cart.items.filter((i) => qualifies(i) && i.variant_id !== giftVariantId);
const gifts = cart.items.filter((i) => i.properties?._gift === '1');
// add any missing gift and adjust quantity; cascade delete handles removal.
The details that keep it from falling over
This is what separates a demo from something that survives production:
- Reentrancy guard. An
inFlightflag so a change in the middle of an add doesn’t trigger another evaluation on top of it. - Detecting cart changes. You can patch
window.fetchto react to/cart/(add|change|update|clear).js, but third-party app drawers sometimes bypass that fetch, so subscribe to your drawer’s events too. - Kill switch. If an add fails several times, turn the feature off for the rest of the page load. A rejected add that retries in a loop takes you straight to rate limiting (429).
- Cache the list of qualifying products in
sessionStorageso you don’t fetch it on every evaluation.
The rule I follow
When Shopify can manage a relationship between cart lines, let Shopify manage it. Your JavaScript should add and sync, not watch and delete. Cascade delete on nested line items is native, free, and it doesn’t fall over.
FAQ
What is parent_line_key in Shopify?
It's a field on /cart/add.js that attaches one line item to another as a child. Shopify treats the new line as a nested line item under its parent line, and cascade deletes it when the parent line is removed.
How do I make the gift cost $0?
With a Shopify automatic discount that targets the gift variant. The price lives in Shopify. Never set it on the client.
Do I need an app for a GWP with cascade delete?
No. With parent_line_key and an automatic discount you can do it in the theme. The JavaScript only adds the gift and syncs the quantity; Shopify handles the removal.