3-tier cart rewards & automatic gifts

01Plan your reward tiers

The interactive demo uses $60 for free express delivery, $100 for a free mystery gift and $150 for 15% off. In a merchant store, use thresholds that support your margins and actual shipping zones. Choose whether eligibility is calculated before or after discounts and use the same rule in the cart and discount configuration.

1. In the theme editor open Theme settings → Cart and enable the reward drawer.
2. Set all three thresholds in ascending order in your store’s base currency.
3. Give each tier a short, explicit label. Avoid promising express shipping to unsupported destinations.
4. Confirm the progress calculation agrees with your selected subtotal rule.

02Create and connect the gift variant

Create a gift product with a tracked inventory policy. Locate its variant ID in Shopify admin or through an authorised API integration. Enter that exact numeric variant ID in the gift setting. A cart UI cannot make an ordinary paid product free on its own.

1. Create the gift product and a purchasable variant with enough stock.
2. Keep gift quantities limited to one per eligible cart.
3. Configure a matching Buy X Get Y automatic discount, or an eligible Shopify Function, to make the gift line free.
4. Define what happens when the gift is sold out; hide the gift promise or offer a valid substitute.

Gift threshold: 100.00
Gift variant: numeric Shopify variant ID
Maximum gift quantity: 1
Eligibility basis: match discount configuration

03Synchronise additions and removals

After a cart mutation, refresh the authoritative cart state, calculate eligibility and add the gift only if it is absent. Mark auto-added gift lines with a private line-item property such as _kiln_reward. Remove only that marked reward line when the cart becomes ineligible; preserve any separately purchased copy of the same product.

1. Use /cart/add.js and /cart/change.js through the storefront’s locale-aware route root.
2. Identify existing cart lines by line key, not by visual row number.
3. Debounce rapid clicks and serialise mutations to avoid duplicate gifts.
4. Re-render totals from the returned cart and announce changes in a polite live region.

04Validate the full journey

Test immediately below, exactly at and above each threshold. Repeat with quantity breaks, codes, subscriptions, multiple currencies and out-of-stock gift variants. Express delivery must be backed by a real Shopify shipping rate or shipping discount.

1. Remove paid items until the gift threshold is no longer met and verify the marked gift disappears.
2. Confirm a customer cannot gain unlimited free gifts by changing quantities.
3. Verify discount combinations in Shopify admin and checkout.
4. Test cart drawer keyboard focus, Escape to close and return focus to its opening button.