Free gift slot events

On this page

Events
Payloads
Examples
Events the widget listens for
Data attributes and states
Product page gift banner
Gift slot
Cart claim rows

This page is for theme developers. The free gift line on product pages, <andor-bundle data-andor-widget="gift">, sends the shared widget events. The line and the cart gift slot also publish upsell offer events for custom pixels.

All DOM events are CustomEvents that bubble, so you can listen on document. The andor:offer_* events are not DOM events. Subscribe to them in a custom pixel.

Note A custom pixel is optional. AndOr counts offers without one. Add a pixel only if you want the andor:offer_* events in your own tools.

Events

Event	Sent on	When
`andor:widget:mount`	the line	the first pass that sees it
`andor:widget:unmount`	the line and `document`	the first pass after it left the page
`andor:display:change`	the line	its state changed, for example it hid
`andor:offer_viewed`	customer events	the offer is first seen, once per offer and placement per visit
`andor:offer_clicked`	customer events	a shopper presses Add gift, Add it back or Choose gift (not Remove gift)
`andor:offer_added`	customer events	a gift was added to the cart
`cart:update`	`document`	Horizon only: the slot removed a gift in the cart drawer

Rules worth knowing:

No event on first paint, and an unchanged state sends nothing.
The cart gift slot is not a widget host. It sends no andor:widget events.
An automatic add has no click before it. It is published as andor:offer_added with auto: true and valueCents: 0.

Payloads

andor:widget:mount, andor:widget:unmount and andor:display:change carry event.detail.resource:

Field	Value for this widget
`widgetType`	`"gift"`
`widgetId`	the block id, or `"pasted"` for a pasted tag
`productId`	`null` (the line carries no product id)

andor:display:change adds previous and current state objects. On this host the useful field is visible. The others are null. See the full payload on Events.

The andor:offer_* events carry event.customData:

Field	Type	Meaning
`offerId`	string	the offer id (digits)
`placement`	string	`"product_page"`, `"cart_page"` or `"cart_drawer"`
`valueCents`	number	adds only: the value of what was added, in cents. `0` for a gift AndOr added for the shopper
`auto`	`true`	only on a gift AndOr added for the shopper

No customer data, cart token or product ids are sent.

cart:update carries Horizon’s own shape:

Field	Value
`detail.resource`	the `/cart.js` response after the removal
`detail.sourceId`	`"andor"`
`detail.data`	`{ source: "andor", itemCount }`

When the slot removes a gift in a cart drawer on Horizon, AndOr sends cart:update so Horizon redraws its cart. On Dawn, AndOr redraws the drawer itself. On the cart page, or on a theme that is neither Dawn nor Horizon, the page reloads instead.

Caution cart:update is Horizon’s contract, not an AndOr API. AndOr sends it only after the slot removes a gift. A gift add does not send it. Listen to it only as Horizon documents it.

Examples

React when the gift line hides:

document.addEventListener("andor:display:change", (event) => {
  const { widgetType, current } = event.detail.resource;
  if (widgetType === "gift" && !current.visible) {
    console.log("free gift line hid");
  }
});

JavaScript

Optional: count gift adds in a custom pixel:

// Shopify admin: Settings > Customer events > Add custom pixel
analytics.subscribe("andor:offer_added", (event) => {
  const { offerId, placement, valueCents, auto } = event.customData;
  console.log(auto ? "gift auto-added" : "gift added", offerId, placement,
    valueCents);
});

JavaScript

shopify:cart:lines-update: the cart changed. The slot reads it again.
shopify:cart:view: the cart drawer opened. The drawer slot draws.
shopify:section:load: the theme editor re-rendered a section.

Data attributes and states

The gift banner uses the same attributes as the bundle card. See Bundle card events.

Gift slot

data-andor-state on .andor-claim__box--gift:

Value	Meaning
`locked`	not earned yet: greyed, no button
`adding`	an automatic add is running (`aria-busy="true"`)
`choose`	earned: add it, or choose one
`removed`	the shopper removed it: “Add it back”
`gone`	chosen, and the cart stopped qualifying
`won`	one line: checkout applied it
`off`	one line: in the cart, another discount won

The button carries data-andor-act: add, open or remove.

Cart claim rows

The gift slot sits in the cart claim host. Its host attributes are on Buy X get Y events.

For the attributes every widget shares, like data-andor-state and data-andor-progress, see Data attributes and states.