> For the complete documentation index, see [llms.txt](https://bogos-api-integration.gitbook.io/bogos-api-integration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/gift-offer.md). # Gift Offer {% hint style="info" %} You can check the integration demo code in [this project](https://github.com/krycek-fengdx/bogos-headless-api/blob/6f4b16654d436107b526b624a6459416dfebe707/app/components/Layout.tsx#L68) and see the basic integration flow. {% endhint %} **Authentication:** every request requires a token and the `verify` header — see [Authentication](/bogos-api-integration/authentication.md). ## Integration flow ```mermaid flowchart TD A[Cart created or updated] --> B{Sync quantity OR
Gift function enabled?} B -- Yes --> C["STEP 2
POST /api-partner/products-sync-quantity"] C --> D[Query gift product quantities
via Shopify Storefront API] D --> E["STEP 1
POST /api-partner/bogos
(cart + eligible productsQuantity)"] B -- No --> E E --> F[Render the gift slider
from the popup field] E --> G["Auto add/update/remove gifts from gifts_change
via cartLinesAdd / cartLinesUpdate / cartLinesRemove
(update with quantity 0 → remove)"] A2[Product / collection page] --> H["STEP 3
POST /api-partner/gift-customize"] H --> I[Render gift icon & gift thumbnail] ``` When **Sync quantity** or the **Gift function** is enabled, call STEP 2 first to learn which gift products need a live quantity check, then pass that data into STEP 1. ## STEP 1: /api-partner/bogos {% hint style="info" %} *This endpoint handles the gift-offer logic of BOGOS (add a gift to the cart, update the number of gifts, or remove a gift from the cart).* {% endhint %} ### 1. Post to `/api-partner/bogos` > 💡 **Example available**\ > 👉 Demo of function [runBOGOS](https://github.com/krycek-fengdx/bogos-headless-api/blob/6f4b16654d436107b526b624a6459416dfebe707/app/bogos/services/bogos.core.ts#L165) #### Request | Field | Type | Required | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `shop` | `string` | Yes | The store's myshopify domain. | | `cart` | [`CartItem[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-3.-cartitem) | Yes | The current cart. | | `customer` | [`Customer`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-8.-customer) | Conditional | Required if a sub-condition uses customer information. | | `productsQuantity` | [`ProductInfo[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-7.-productinfo) | Conditional | Eligible products with verified quantities (from STEP 2). | | `productOptions` | [`ProductOption[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-30.-productoption) | No | Option names and per-variant values, for offers that match the gift to the trigger's option value. Falls back to the data saved on the offer. | | `other` | [`OtherParams`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-1.-otherparams) | No | Locale, country, market, and other context. | ```typescript { shop: string; // myshopify domain cart: CartItem[]; customer?: Customer; // required if a sub-condition uses customer information productsQuantity?: ProductInfo[]; productOptions?: ProductOption[]; other?: OtherParams; } ``` **Example** ```json { "shop": "your-store.myshopify.com", "cart": [ { "id": "gid://shopify/CartLine/abc123", "variant_id": 43210987654321, "product_id": 7891234567890, "product_title": "Classic T-Shirt", "handle": "classic-t-shirt", "vendor": "Acme", "product_type": "Apparel", "collections": [{ "id": 123456789, "title": "Summer" }], "price": 120.0, "quantity": 1, "tags": [], "properties": [] } ], "other": { "countryCode": "US", "languageCode": "en" } } ``` #### Response | Field | Type | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `popup.data` | [`GiftProduct[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-12.-giftproduct) | Gifts to show in the slider (when the gift slider is in use). | | `popup.customize` | [`GiftSliderCustomize`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-5.-giftslidercustomize) | Slider UI settings. | | `gifts_change.add` | [`GiftChangeAdd[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-13.-giftchangeadd) | Gifts not yet in the cart → add them automatically. | | `gifts_change.update` | [`GiftChangeUpdate[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-14.-giftchangeupdate) | Gifts already in the cart → update their quantity automatically. | | `codes` | `string[]` | Discount codes used to discount the gift product (optional). | | `cart_message.data` | [`CartMessage[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-15.-cartmessage) | Messages to render in the cart. | | `cart_message.customize` | [`CartMessageCustomize`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-16.-cartmessagecustomize) | Cart-message UI settings. | | `today_offers.data` | [`TodayOffer[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-18.-todayoffer) | Currently available offers on the store. | | `today_offers.customize` | [`TodayOfferCustomize`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-19.-todayoffercustomize) | Today-offer widget UI settings. | ```typescript { popup: { data: GiftProduct[]; // shown if the gift slider is in use customize: GiftSliderCustomize; }; gifts_change: { // gift products that changed in the cart add: GiftChangeAdd[]; // gift not in cart → added automatically update: GiftChangeUpdate[]; // gift already in cart → quantity changed automatically }; codes?: string[]; // present when a discount code is used to discount the gift product cart_message: { data: CartMessage[]; // shown if the cart message is in use customize: CartMessageCustomize; }; today_offers: { data: TodayOffer[]; // list of currently available offers customize: TodayOfferCustomize; }; } ``` **Example** (`customize` objects elided as `{}` for brevity — each follows its `*Customize` type) ```json { "popup": { "data": [ { "id": 7899999999999, "title": "Free Tote Bag", "handle": "free-tote-bag-sca_clone_freegift", "thumbnail": "https://cdn.shopify.com/s/files/tote.jpg", "belongs_to_offer": "10023", "variants": [ { "id": 43200000000001, "discount_type": "percentage", "discount_value": 100, "original_price": 15.0, "price": 0, "title": "Default Title", "properties": { "_bogos_trigger_id": "10023", "_bogos_trigger": "cart_value", "_bogos_trigger_type": "amount" } } ] } ], "customize": {} }, "gifts_change": { "add": [ { "variant_id": 43200000000001, "belongs_to_offer": "10023", "quantity": 1, "properties": { "_bogos_trigger_id": "10023", "_bogos_trigger": "cart_value", "_bogos_trigger_type": "amount" } } ], "update": [] }, "cart_message": { "data": [], "customize": {} }, "today_offers": { "data": [], "customize": {} } } ``` {% hint style="warning" %} The `properties` values are returned by the API. **Echo them verbatim** when you add the gift to the cart so BOGOS can recognize it. The values above are illustrative. {% endhint %} ### 2. Use the response data to display gifts in your sales channels The response data, including the gift product ID, is used to display gifts in your sales channels. * For a gift that is **added automatically** to the cart, use the **`gifts_change`** field. *See how to use the Storefront API to add/remove a cart line* [*here*](https://shopify.dev/docs/api/storefront/latest/mutations/cartLinesAdd). * For a gift the customer **selects** from the slider, use the **`popup`** field. {% hint style="warning" %} When a `gifts_change.update` entry returns `quantity: 0`, the gift is no longer awarded and should be **removed** from the cart — not updated. Call the remove cart-line API ([`cartLinesRemove`](https://shopify.dev/docs/api/storefront/latest/mutations/cartLinesRemove)) for that line instead of the update API ([`cartLinesUpdate`](https://shopify.dev/docs/api/storefront/latest/mutations/cartLinesUpdate)). {% endhint %} > 💡 **Example available**\ > 👉 Demo of function [showGiftSlider](https://github.com/krycek-fengdx/bogos-headless-api/blob/6f4b16654d436107b526b624a6459416dfebe707/app/bogos/services/bogos.core.ts#L265C14-L265C28)

Example of a gift slider displayed in the storefront

## STEP 2: /api-partner/products-sync-quantity {% hint style="info" %} *Fetch the gift products whose quantity must be verified. Required when **Settings → Sync quantity** (gift inventory management) is enabled **or** when you use the **Gift function** — both rely on this endpoint to get up-to-date gift product information before calling STEP 1.* {% endhint %}

Sync quantity integration flow

**How it works:** post to `/api-partner/products-sync-quantity` to get the list of gift product IDs that need a live quantity check. Use the Storefront API to read those products' current quantities ([example](https://shopify.dev/docs/api/storefront/latest/queries/search)), then call [STEP 1](#step-1-api-partner-bogos) with the eligible product data in `productsQuantity`. > 💡 **Example available**\ > 👉 Demo of function [getProductsSyncQuantity](https://github.com/krycek-fengdx/bogos-headless-api/blob/6f4b16654d436107b526b624a6459416dfebe707/app/bogos/services/bogos.local.ts#L48C16-L48C39) #### Request | Field | Type | Required | Description | | ------ | -------- | -------- | --------------------------------------------------------------------- | | `shop` | `string` | Yes | The store's myshopify domain (sent as a query param and in the body). | ```typescript { shop: string; // myshopify domain } ``` **Example** ```json { "shop": "your-store.myshopify.com" } ``` #### Response An array of [`ProductSyncQuantity`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-21.-productsyncquantity) — the gift products to verify. ```typescript ProductSyncQuantity[] ``` **Example** ```json [ { "id": 7899999999999, "handle": "free-tote-bag-sca_clone_freegift", "variants": [43200000000001] } ] ``` {% hint style="info" %} For partners and users who integrated before **Nov 6, 2024**, you must update your integration with these fields: ```typescript codes?: string[]; // present when a discount code is used to discount the gift product ``` ```typescript properties?: { // properties identify which cart item is a gift _bogos_trigger_id: string; _bogos_trigger: string; _bogos_trigger_type: string; } ``` {% endhint %} ## STEP 3: /api-partner/gift-customize {% hint style="info" %} *Returns the customization for the gift icon, the product-page message, and the gift products awarded for buying specific products or variants.* {% endhint %} > 💡 **Example available**\ > 👉 Demo of function [bogosCheckProductHasGifts](https://github.com/krycek-fengdx/bogos-headless-api/blob/6f4b16654d436107b526b624a6459416dfebe707/app/bogos/components/gift.icon.tsx#L27C22-L27C47) #### Request | Field | Type | Required | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `shop` | `string` | Yes | The store's myshopify domain. | | `products` | [`ProductInfo[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-7.-productinfo) | Yes | Products to check for gift eligibility. | | `productsQuantity` | [`ProductInfo[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-7.-productinfo) | Conditional | Required if Sync quantity is in use. | | `productOptions` | [`ProductOption[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-30.-productoption) | No | Option names and per-variant values, for offers that match the gift to the trigger's option value. Falls back to the data saved on the offer. | | `customer` | [`Customer`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-8.-customer) | Conditional | Required if a sub-condition uses customer information. | | `other` | [`OtherParams`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-1.-otherparams) | No | Locale, country, market, and other context. | ```typescript { shop: string; // myshopify domain products: ProductInfo[]; productsQuantity?: ProductInfo[]; productOptions?: ProductOption[]; customer?: Customer; // required if a sub-condition uses customer information other?: OtherParams; } ``` **Example** ```json { "shop": "your-store.myshopify.com", "products": [ { "id": 7891234567890, "handle": "classic-t-shirt", "title": "Classic T-Shirt" } ] } ``` #### Response | Field | Type | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `data` | [`ProductHasGifts[]`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-20.-producthasgifts) | All requested products; gifts (if any) appear in `gifts_will_receive`. | | `icon` | `string` | The gift icon image URL. | | `enableForAllCondition` | `boolean` | Whether the gift icon is enabled for all main conditions. | | `customize` | `object` | Gift icon / thumbnail UI settings (see below). | ```typescript { data: ProductHasGifts[]; // all products from the request body; if a gift is associated // with a product, it appears in the gifts_will_receive property icon: string; // icon link enableForAllCondition: boolean; customize: { // In-app → Customize → Gift icon collection_page: { status: boolean; size: number; }; product_page: { gift_icon: { status: boolean; size: number; }; gift_thumbnail: { status: boolean; size?: number; title?: string; number_text?: string; border_color?: string; show_multiple?: string; countdown_text?: string; use_old_version?: boolean; offer_name_color?: string; show_number_gift?: boolean; countdown_time_color?: string; show_countdown_timer?: boolean; }; }; }; } ``` **Types referenced:** [`ProductHasGifts`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-20.-producthasgifts), [`ProductInfo`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-7.-productinfo), [`ProductOption`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-30.-productoption), [`Customer`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-8.-customer), [`OtherParams`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-1.-otherparams), [`GiftProduct`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-12.-giftproduct), [`ProductSyncQuantity`](https://bogos-api-integration.gitbook.io/bogos-api-integration/integration-steps/pages/qrsVHOlaqKDffncixXkj#id-21.-productsyncquantity).