BYOB SDK

window.eliteBundle.sdk.byob — live BYOB state and actions, updated on every React render.

Available after the elite:byob:ready event fires. null when no BYOB bundle is on the current page.

---

State

bundleId

string

The Shopify product ID of the bundle. Stable identifier — use this to associate external state with a specific bundle.

---

steps

ResolvedStep[]

All configured bundle steps, each populated with fetched Shopify product and variant data.

interface ResolvedStep {
  id: string;
  title: string;
  minQuantity: number;
  maxQuantity: number | null;
  enableSelectionLimit: boolean;
  products: ShopifyProduct[];
}

interface ShopifyProduct {
  id: string;
  title: string;
  handle: string;
  featuredImage: { url: string; altText: string | null } | null;
  variants: ProductVariant[];
}

interface ProductVariant {
  id: string;          // GID, e.g. "gid://shopify/ProductVariant/123"
  title: string;       // e.g. "Red / Small"
  price: string;       // numeric string, e.g. "29.99"
  available: boolean;
  image: { url: string; altText: string | null } | null;
  selectedOptions: { name: string; value: string }[];
}

Example:

document.addEventListener('elite:byob:ready', () => {
  const { steps } = window.eliteBundle.sdk.byob;
  steps.forEach(step => {
    console.log(step.title, step.minQuantity, step.maxQuantity);
    step.products.forEach(p => {
      console.log(p.title, p.variants.map(v => v.price));
    });
  });
});

---

isLoading

boolean

true while products are being fetched from the Storefront API. The elite:byob:ready event only fires after this becomes false.

---

error

string | null

Non-null when product fetching failed. The elite:byob:error event fires at the same time.

---

cart

CartItem[]

Current bundle cart contents.

interface CartItem {
  variantId: string;
  stepId: string;
  title: string;         // product title
  variantTitle: string;  // e.g. "Red / Small"
  price: number;         // numeric, in store currency
  quantity: number;
  imageUrl: string | null;
}

---

cartTotal

number

Sum of price × quantity for all cart items. Rounded to 2 decimal places.

---

cartTotalFormatted

string

cartTotal formatted using the store's money format, e.g. "$49.99". Use this for display.

---

cartCount

number

Total quantity of items across all cart entries.

---

canCheckout

boolean

true when all steps with minQuantity constraints are satisfied. Gate your checkout button on this.

---

isTierMaxReached

boolean

true when cartCount has reached the highest discount tier's quantity threshold. Useful for hiding "add more for a discount" prompts.

---

isCheckingOut

boolean

true while the cart POST request is in flight. Use to show a loading state on your checkout button.

---

checkoutError

string | null

Non-null when the last checkout attempt failed. The elite:byob:checkout-error event also fires.

---

discountConfig

DiscountSettings

The discount configuration for this bundle. Inspect this to build a tier progress indicator.

type DiscountSettings =
  | { discountType: "none" }
  | { discountType: "percentage"; tiers: DiscountTier[] }
  | { discountType: "fixed"; tiers: DiscountTier[] };

interface DiscountTier {
  minQuantity: number;
  discountValue: number;
}

Example:

const { discountConfig, cartCount } = window.eliteBundle.sdk.byob;

if (discountConfig.discountType !== "none") {
  const nextTier = discountConfig.tiers.find(t => t.minQuantity > cartCount);
  if (nextTier) {
    const remaining = nextTier.minQuantity - cartCount;
    console.log(`Add ${remaining} more for ${nextTier.discountValue}% off`);
  }
}

---

Actions

formatPrice(amount)

formatPrice(amount: number): string

Formats a numeric amount using the store's money format and active currency rate.

const { formatPrice, cartTotal } = window.eliteBundle.sdk.byob;
console.log(formatPrice(cartTotal)); // "$49.99"

---

addToCart(product, variantId, stepId?)

addToCart(product: ShopifyProduct, variantId: string, stepId?: string): void

Adds one unit of a variant to the bundle cart. Pass the full product object and the variant GID.

stepId is optional — when omitted, the system uses the variant's resolved step automatically.

const { steps, addToCart } = window.eliteBundle.sdk.byob;
const step = steps[0];
const product = step.products[0];
const variant = product.variants[0];

addToCart(product, variant.id, step.id);

---

removeFromCart(variantId, stepId?)

removeFromCart(variantId: string, stepId?: string): void

Removes all units of a variant from the cart. Include stepId if the same variant can appear in multiple steps.

---

updateQuantity(variantId, delta, stepId?)

updateQuantity(variantId: string, delta: number, stepId?: string): void

Increments or decrements the quantity of a cart item. Use +1 or -1. If quantity reaches 0, the item is removed.

// Add one more
window.eliteBundle.sdk.byob.updateQuantity(variantId, 1, stepId);

// Remove one
window.eliteBundle.sdk.byob.updateQuantity(variantId, -1, stepId);

---

getItemQuantity(variantId, stepId?)

getItemQuantity(variantId: string, stepId?: string): number

Returns the current quantity of a specific variant in the cart. Returns 0 if not present.

const qty = window.eliteBundle.sdk.byob.getItemQuantity(variantId, stepId);
document.querySelector('.qty-badge').textContent = qty;

---

isStepFull(stepId)

isStepFull(stepId: string): boolean

Returns true when a step has enableSelectionLimit enabled and its maxQuantity has been reached. Use to disable the add button for a step.

---

canAddToStep(stepId)

canAddToStep(stepId: string): boolean

Returns true when adding another item to this step is still allowed. Inverse of isStepFull for steps with a limit; always true for unlimited steps.

const { canAddToStep } = window.eliteBundle.sdk.byob;
step.products.forEach(product => {
  addBtn.disabled = !canAddToStep(step.id);
});

---

checkout(redirectTarget?)

checkout(redirectTarget?: "checkout" | "cart" | "stay_on_page"): Promise<void>

Posts the bundle cart to Shopify and handles the redirect.

redirectTarget	Behavior
"checkout" (default)	Redirects to Shopify checkout
"cart"	Redirects to /cart
"stay_on_page"	No redirect — stays on the product page

document.querySelector('#my-checkout-btn').addEventListener('click', () => {
  window.eliteBundle.sdk.byob.checkout('checkout');
});

---

Full example

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

  // Render steps
  sdk.steps.forEach(step => {
    const stepEl = renderStep(step);
    step.products.forEach(product => {
      product.variants.forEach(variant => {
        const btn = renderAddButton(product, variant);
        btn.disabled = !sdk.canAddToStep(step.id) || !variant.available;
        btn.addEventListener('click', () => sdk.addToCart(product, variant.id, step.id));
        stepEl.appendChild(btn);
      });
    });
    document.querySelector('#steps').appendChild(stepEl);
  });

  // Checkout button
  const checkoutBtn = document.querySelector('#checkout-btn');
  checkoutBtn.addEventListener('click', () => sdk.checkout());
});

document.addEventListener('elite:byob:cart-change', (e) => {
  const { cart, cartTotalFormatted, canCheckout } = e.detail;
  document.querySelector('#total').textContent = cartTotalFormatted;
  document.querySelector('#checkout-btn').disabled = !canCheckout;
  renderCartItems(cart);
});