> For the complete documentation index, see [llms.txt](https://docs.elitebundleapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elitebundleapp.com/reference/events.md).

# Events

Reference for the elite:byob:\* bundle events and elite:upsell:\* upsell events Elite Bundle Builder fires, with payloads and examples.

All events are dispatched on `document` as `CustomEvent` instances with `bubbles: true`. Listen with `document.addEventListener`, or with `window.eliteBundle.on` / `.off` once the bundle script has loaded.

The six `elite:byob:*` events below cover **both** bundle types — a multi-option bundle fires the same `elite:byob:*` events as a build-your-own bundle. See the [Bundle SDK](https://docs.elitebundleapp.com/reference/sdk.md) for why the two share one surface.

```js
document.addEventListener('elite:byob:ready', () => {
  const sdk = window.eliteBundle.sdk?.byob;
});
```

> `window.eliteBundle.on` is added by the bundle script, which loads deferred. Theme code that runs earlier should use `document.addEventListener` directly — the events fire on `document` either way.

***

### `elite:byob:ready`

Fired once the bundle has finished loading its products and rendered. This is the safe point to start reading `window.eliteBundle.sdk.byob`.

It can fire again if the bundle reloads its products, so make your handler safe to run more than once.

**Detail:**

```ts
{
  bundleId: string;   // Shopify product ID
  stepCount: number;  // number of steps (options, for a multi-option bundle)
}
```

```js
document.addEventListener('elite:byob:ready', (event) => {
  const { bundleId, stepCount } = event.detail;
  const sdk = window.eliteBundle.sdk?.byob;
  if (sdk) renderMySteps(sdk.steps);
});
```

***

### `elite:byob:error`

Fired when the bundle fails to load — a Storefront API error, a network failure, or a missing configuration.

**Detail:**

```ts
{
  error: string; // a shopper-facing message, safe to display as-is
}
```

The detail is a single generic message. The diagnostic detail is logged to the browser console instead, so there is nothing more specific to surface.

***

### `elite:byob:cart-change`

Fired whenever the selection or the checkout state changes — including once on first load, so a handler alone is enough to render your initial UI. `window.eliteBundle.sdk.byob` is already updated when it fires, including `steps`: a step with a **Show this step** rule appears or disappears with the picks, so re-render your steps when their ids change.

**Detail:**

```ts
{
  cart: CartItem[];
  cartTotal: number;    // rounded to 2 decimals
  cartCount: number;
  canCheckout: boolean;
}
```

The detail carries the **raw** total. Use `sdk.formatPrice(cartTotal)`, or read `sdk.cartTotalFormatted`, to display it. While the shopper has a subscription selected, `cartTotal` is the total on that plan, before the bundle discount.

```js
document.addEventListener('elite:byob:cart-change', (event) => {
  const { cart, cartTotal, cartCount, canCheckout } = event.detail;
  const sdk = window.eliteBundle.sdk?.byob;

  document.querySelector('#cart-count').textContent = cartCount;
  document.querySelector('#cart-total').textContent = sdk.formatPrice(cartTotal);
  document.querySelector('#checkout-btn').disabled = !canCheckout;
});
```

***

### `elite:byob:checkout-start`

Fired when the bundle starts being added to the Shopify cart. Use it to show a loading state.

**Detail:**

```ts
{
  cart: CartItem[];
  cartTotal: number;
  cartCount: number;
}
```

As in `cart-change`, `cartTotal` is the total on the chosen plan when the shopper is subscribing.

***

### `elite:byob:checkout-success`

Fired after the bundle is added to the cart, before any redirect.

**Detail:**

```ts
{
  redirectTarget: "stay_on_page" | "cart" | "checkout";
}
```

The bundle is emptied at this point and a new bundle session begins. With `stay_on_page`, expect a follow-up `cart-change` with an empty cart.

***

### `elite:byob:checkout-error`

Fired when adding to the cart fails — for example a variant that sold out between selection and checkout.

**Detail:**

```ts
{
  error: string;
}
```

***

## Upsell events

Two more events fire on the product pages where a bundle's [upsell card](https://docs.elitebundleapp.com/grow-and-manage/upsells.md) shows. They are on every page with a card, not only on bundle pages, and they do not need SDK access turned on. One card is one bundle, so a page with two cards fires two `view` events.

### `elite:upsell:view`

Fired once per card per page load, when at least half of the card is on screen.

### `elite:upsell:click`

Fired when the shopper clicks the card's button, just before the browser follows the link to the bundle.

**Detail (both events):**

```ts
{
  bundleId: string;       // Shopify product ID of the promoted bundle
  handle: string;         // its product handle
  fromProductId: string;  // Shopify product ID of the page the card is on
}
```

```js
document.addEventListener('elite:upsell:click', (event) => {
  const { bundleId, fromProductId } = event.detail;
  window.dataLayer?.push({ event: 'bundle_upsell_click', bundleId, fromProductId });
});
```

### In a custom web pixel

The same two moments are also published to Shopify's analytics as the custom events `eb_upsell_view` and `eb_upsell_click`, which is what the app's own upsell analytics read. A [custom pixel](https://help.shopify.com/en/manual/promoting-marketing/pixels/custom-pixels) can subscribe to them too, and Shopify applies the shopper's privacy choices before it runs:

```js
analytics.subscribe('eb_upsell_click', (event) => {
  const { bundleProductId, fromProductId } = event.customData;
});
```

***

## Event timing

`elite:byob:ready` may fire before your own script runs. Handle both cases by checking whether the SDK is already populated:

```js
function onBundleReady(callback) {
  const sdk = window.eliteBundle?.sdk?.byob;
  if (sdk && !sdk.isLoading && !sdk.error) {
    callback();          // already loaded
  } else {
    document.addEventListener('elite:byob:ready', callback, { once: true });
  }
}
```

Do not gate this on `window.eliteBundle.sdk` existing — the bundle script is deferred, so `sdk` appears later than `window.eliteBundle` itself. Listening on `document` always works.
