BOGOS JS/SDK

Version source

  BOGOS_JS_SDK=https://cdn.bogos.io/bogos-app-ext/20250905-1757090109/core.min.js

Requirements

Your store must be built using the Storefront API.
Always create a cart after applying BOGOS to ensure the cart ID is received correctly. Example
For advanced customization in your Headless store, refer to the BOGOS API documentation.

Installation

Step 1: Getting started

Add the following script to your project:
```
<script id="bogos-core" src={{BOGOS_JS_SDK}} defer
  data-storefront-api-token={{PUBLIC_STOREFRONT_API_TOKEN}}
  data-api-version={{PUBLIC_STOREFRONT_API_VERSION}}
  data-myshopify-domain={{MYSHOPIFY_DOMAIN}}
  data-bogos-key={{BOGOS_KEY}}
/>
```
Property
Description
Example
VERSION_SOURCE: String!
The script URL for the current version
https://cdn.bogos.io/{{version}}/core.min.js
PUBLIC_STOREFRONT_API_TOKEN: String!
Public Storefront API token
abcd...
PUBLIC_STOREFRONT_API_VERSION: String!
Storefront API version
2025-04
MYSHOPIFY_DOMAIN: String!
Myshopify domain (found in Shopify Admin > Settings)
bogos.myshopify.com
BOGOS_KEY: String!
Key generated by the BOGOS app
bogoskey...
💡 Example Available 👉 root.tsx

Update your project with the required BOGOS data:

typeof window !== 'undefined' && typeof window.BOGOS_CORE !== 'undefined' &&
  window.BOGOS_CORE?.helper?.updateCore(option: BOGOSOptions)

export type BOGOSOptions = {
  cart?: Cart;
  customer?: string | Customer;
  locale?: string; https://shopify.dev/docs/api/storefront/latest#@inContext-(Language)
  country?: string; https://shopify.dev/docs/api/storefront/latest#@inContext-(Country-Code)
  currency?: {
    active: string;
    rate: number;
  };
};

Note:

You must provide at least one of the above properties.
If you provide the full Cart object, BOGOS will not fetch the cart again.
If only the Cart ID is provided, BOGOS will fetch the cart again.
The customer parameter can be either a customer access token or customer object

💡 Example Available 👉 root.tsx 👉 Layout.tsx 👉 Cart.tsx

Step 2: Gift Offer

Trigger the gift logic whenever the cart is updated:
```
  typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent('bogos:gifts', { detail: cart }));
```
Note:
- cart: Cart
- If you provide the full Cart, it won’t fetch again.
- If only the Cart ID is provided, it will fetch again.
💡 Example Available 👉 Cart.tsx

Add prepareCheckout to your checkout process to validate gift items before proceeding to checkout:


async function {your_function_checkout} (args) {
    ...
    typeof window !== 'undefined' && typeof window.BOGOS_CORE !== 'undefined' &&
      await BOGOS_CORE?.helper?.gift?.prepareCheckout();
    ...
}

💡 Example Available 👉 Cart.tsx

Customize

3.1. Gift Icon & Gift thumbnail

On the product page Add class "fg-secomapp-product-title" where you want to display gift icon Add class "bogos-gift-thumbnail-view" where you want to display gift thumbnail

typeof window !== 'undefined' && window.BOGOS_CORE?.helper?.gift?.renderCustomizeForProduct([{ id: product_id }], { product: true });

// An event is triggered for all customizations on the product page
typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
  detail: {
    products: [{ id: product_id }],
    options: { product: true, selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] }
  }
}));

💡 Example Available 👉 products.$handle.tsx

For collection page Add class "fg-secomapp-collection-img" to where you want to display gift icon on product card

typeof window !== 'undefined' && window.BOGOS_CORE?.helper?.gift?.renderCustomizeForProduct([{ id: product.id }], { collection: true });

💡 Example Available 👉 collections.$handle.tsx

3.2. Cart message

Add the class "bogos-cart-message-view" to the element where you want the message displayed

<div class="bogos-cart-message-view"></div>

3.3. Gift slider

To embed the gift slider instead of displaying as a popup, include the following code:

<div id="freegifts-main-page-container"></div>

Step 3: Bundle Offer

Classic bundle

Add the following element to where you want to display the bundle offer.

  <div id="bogos-bundle-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>

  /* 
    product_id: number; legacy product id
    offer_id: number; BOGOS offer id
  */

Dispatch this element to render the bundle offer

  typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:bundle-init"));

// An event is triggered for all customizations on the product page
typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
  detail: {
    products: [{ id: product_id }],
    options: { 
      product?: true, 
      selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] 
    }
  }
}));

💡 Example Available 👉 products.$handle.tsx

Mix-match

Add the following element to where you want to display the bundle offer.

  <div id="bogos-mix-match-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>

  /* 
    product_id: number; legacy product id
    offer_id: number; BOGOS offer id
  */

Dispatch this element to show bundle offer

  typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:bundle-init"));

// An event is triggered for all customizations on the product page
typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
  detail: {
    products: [{ id: product_id }],
    options: { 
      product?: true, 
      selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] 
    }
  }
}));

💡 Example Available 👉 products.$handle.tsx

Step 4: Bundle Page

Add the following element to where you want to display the bundle offer.

  <div id="bogos-bundle-page-view" data-offer-id={{offer_id}}></div>

  /* offer_id: number; BOGOS offer id */

Dispatch this element to render the bundle offer.

  typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:bundle-page-init"));

💡 Example Available 👉 bundle-page.$id.tsx

Step 5: Upsell Offer

Frequently Bought Together (FBT)

Add the following element to where you want to display the upsell offer

  <div id="bogos-fbt-upsell-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>

  /* 
    product_id: number; legacy product id
    offer_id: number; BOGOS offer id
  */

Dispatch this element to render the upsell offer

  typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:upsell-init"));

💡 Example Available 👉 products.$handle.tsx

Step 6: Discount Offer

Volume Discount

Add the following element to where you want to display the discount offer

  <div id="bogos-volume-discount-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>

  /* 
    product_id: number; legacy product id
    offer_id: number; BOGOS offer id
  */

Dispatch this element to render the discount offer

  typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:discount-init"));

// An event is triggered for all customizations on the product page
typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
  detail: {
    products: [{ id: product_id }],
    options: { 
      product?: true, 
      selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] 
    }
  }
}));

💡 Example Available 👉 products.$handle.tsx

Step 7: Other integration

Hide gift (cloned product) from appearing in your headless store
- If you use products query, you should add : query: "tag_not:bogos-gift"
```
products (
    ...,
    query: "tag_not:bogos-gift"
) {
...
}
```
- For collection and product page, you can import checkItemIsGift and use returned value to skip gift products or replace to other pages
```
export type ProductObject = {
    handle: string;
    tags: string[];
    variant_id: number;
};

/* item can be product handle */
checkItemIsGift: (item: string | ProductObject) => boolean;
```
💡 Example Available 👉 collections.$handle.tsx 👉 products.$handle.tsx

Customize gift popup/slider

Hide all default gift slider elements, and override with your custom implementation.

  #freegifts-main-popup-container, #freegifts-main-page-container {
    display: none !important;
  }

type GiftItem = {
    id: number;
    discount_type: 'percentage' | 'fixed_amount';
    discount_value: number;
    original_price: number;  // Original price - price before discount
    price: number;           // Discount price - price after discount
    title: string;
    thumbnail?: string;
};

type GiftProduct = {
    id: number;
    title: string;
    handle: string;
    thumbnail?: string;
    belongs_to_offer: string;
    variants: GiftItem[];
};

document.addEventListener("fg-gifts:show-slider", (e) => {
    console.log((e as CustomEvent).detail);
    /* render gift slider with detail {
        addGiftToCartFunc: (variant_id: number, quantity: number, offer_id: number) => {};
        gifts?: GiftProduct[]; // show all gifts
        giftsOffer?: { // show gifts by offer
          arrGiftShow: GiftProduct[];
        }
    } */
});

Details of additional event listeners.

fg-gifts:updated

document.addEventListener("fg-gifts:updated", (e) => {
    /* use this function to re-render cart */
    console.log((e as CustomEvent).detail);
});

💡 Example Available 👉 Layout.tsx

fg-cart:auto-updated: Event gift auto add

document.addEventListener("fg-cart:auto-updated", (e) => {
    console.log((e as CustomEvent).detail);
});

fg-gifts:added: Event add gift from slider, will not work if you customize gifts popup

document.addEventListener("fg-gifts:added", (e) => {
    console.log((e as CustomEvent).detail);
});

You can log to view detail data

fg-gifts:gift-icon: Show gift icons
bogos:message: Show cart message

Some features are not yet available on this version yet
- Draft-Order API
- Automatic volume discount
- Bundle page button block
- Some Shopify object-based params (if only id provided, BOGOS will fetch the rest).

Notice

Publish Gift/Cloned Products

After creating or editing an offer, ensure that the gift/cloned product is published to your Headless channel (or any channel where you want BOGOS to run).

Additional Customization

For deeper customization, please contact our support team.

Support

BOGOS: Free Gift - help@bogos.io

You can also reach our live chat support directly within the app from your Shopify Admin.

PreviousBundle Offer

Last updated 8 days ago