← Back to the blog

Themes

Shopify GWP: make the gift remove itself when its product is removed

How to tie a gift to its product with nested line items (parent_line_key) and let Shopify remove it with cascade delete, instead of watching the cart with fragile JavaScript.

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 inFlight flag 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.fetch to 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 sessionStorage so 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.