Gift Selector

The Gift Selector is how shoppers claim the gifts a gift-with-purchase discount unlocks. When the cart crosses a tier, a dialog opens with one slot per gift, the tier’s products to choose from, a selection tray that shows what has been picked so far, and a single Add to cart that writes every filled slot at once. Once the gifts are in the cart, a Change gifts trigger lets the shopper swap them.

It is built on the Quickview — the same dialog, opened in its selection mode — so everything the quickview does (option pickers, swatches, variant availability, the Storefront and Ajax product sources, brand tokens, CSS parts) applies here too. The two are documented separately because they are used differently: the quickview is a trigger you place on a product; the gift selector opens itself from the Gift with purchase app embed, and the only element you place for it is the change-gifts trigger in the cart.

How it opens

The Gift with purchase app embed is the orchestrator: it watches the cart, works out which tiers are unlocked, adds single-option gifts by itself, removes gifts whose trigger lapsed, and — with Use the Live quickview (beta) on and the Discount Kit Live embed enabled — opens the gift selector for anything with a choice. Without the Live embed, or with the setting off, the classic gift selector modal opens as before.

Each unlocked tier becomes a group of choices with as many slots as the tier gives gifts. A tier with one product opens straight on that product; a tier with several shows a picker first. The product screen’s action reads Add gift 1 of 3 and fills the tray cell ringed in the accent colour; the tray’s count keeps score (1 of 3 chosen). Tiers are claimed whole: Add to cart writes every completed tier and leaves a half-picked one open.

Settings

All on the Gift with purchase app embed, under Use the Live quickview (beta):

Message and Add to cart label — the dialog’s heading and its add-all button.
Add default gifts when the quickview is closed (off by default). Closing without finishing still claims the gifts: whatever the shopper picked stays, and every slot they left empty is filled with the first available option its tier offers. The lines are written through the same path as every other gift, so the selector doesn’t reopen and the gifts behave exactly as if they had been chosen. Leave it off if you rely on Stop showing after — a close then means “no, thanks”, as it always has.
Show a “Change gifts” button in the cart (off by default). Places a <dkl-change-gifts> trigger under every checkout button while a claimed gift has a real choice. Its text and style (match the theme’s checkout button, or a Discount Kit button in your brand colours) are settings.
Show on cart page only and Stop showing after gate the automatic opens exactly as they did for the classic modal. A shopper’s own click on Change gifts is never gated.

Using it alongside the Quickview

Both are one dialog, so they coexist without any wiring:

One dialog per page. A product-card quickview trigger and the gift selector share the same element. Whichever opens last takes the dialog over; a gift selector opening on top of a quickview add is the normal “you just unlocked a gift” moment.
Adds from the quickview count. When a shopper adds from a quickview and the cart crosses a tier, the embed runs its cart pass and opens the gift selector — from inside the same dialog if the quickview is still open (closeOnAdd off), or fresh if it closed. Nothing to configure.
Styling is shared. Brand tokens, the quickview’s CSS parts and its labels reach the gift selector unchanged; the selection tray and the change-gifts button add their own tokens and parts on top.
Product data is shared. Whatever product source the quickview uses — the Storefront API with swatches, the Ajax API, or a Liquid seed — the gift selector uses for gift products. High-variant gift products get the same availability handling.
Cart writes are separate. The quickview writes through the theme’s standard cart actions or /cart/add.js. The gift selector’s writes go through the embed’s own cart path (the one that also removes lapsed gifts), so gift lines always carry the properties the discount function looks for.

The Gift with purchase embed opens the selector; a quickview trigger is placed by you. If you want to open the selector yourself, that’s the JavaScript API.

Common set-ups

Ask once, default the rest. Add default gifts when closed on, Show a “Change gifts” button on. The selector opens when a tier unlocks; a shopper who closes it still gets their gifts, and can change their mind from the cart. The least friction with a choice still on offer.

Never interrupt the product page. Show on cart page only on, the change button on. Gifts are picked when the shopper is already in the cart, and never over a product they are reading about. Pair with Add default gifts when closed so a shopper who heads straight to checkout from a drawer still has their gifts.

Pick a colour. A tier whose rule names one product’s variants — the gift bottle in any of three colours. The selector opens straight on the product with only those colours offered; no picker screen, no back arrow.

Tiered gifts. “One gift at $50, two more at $100.” Each tier is its own captioned section of the tray. A shopper at $100 can claim tier 1 without touching tier 2, and when they come back for tier 2 the first tier is already in the cart.

Gift from a collection. A tier that offers any of six products. The picker shows the six as cards; picking one opens its options; the tray fills as they go. Cards that have nothing purchasable are disabled rather than hidden, so the offer still reads as six.

Your own cart drawer. Turn the automatic button off and drop <dkl-change-gifts> into the drawer’s footer with your own markup; it hides itself when there is nothing to change. See Web Component.

A custom gift experience. Turn the selector off, listen to the embed’s discount_kit:gift_adjustments, and open selection mode yourself with your own copy and layout rules — the JavaScript API has a worked example.

Changing gifts

The change trigger reopens the dialog on the claimed tiers with the gifts already in the cart pre-filled. The action reads Change gift 2 of 3 on a slot that already holds a gift and stays disabled while the selected options are the gift that is already there; Add to cart then replaces the old lines with the new ones in a single cart write.

Web ComponentPlace your own trigger anywhere in the cart.

JavaScript APIOpen selection mode yourself, own the cart write, and reword every label.

StylingTokens for the change-gifts button and CSS parts for the selection tray.

EventsSelection changes, the add-to-cart payload in selection mode, and the change-gifts decision.