Gift Offer

STEP 1: /api-partner/bogos

/api-partner/bogos handles the logic of BOGOS related to gift offer (add gift to cart, update number of gift, remove gift from cart)

1. Post /api-partner/bogos

• Body

{
  shop: string; // myshopify domain

  cart: CartItem[];

  customer?: Customer; // required if sub-condition with customer information is in use

  productsQuantity?: ProductInfo[];

  other?: OtherParams;
}

• Response

{
  popup: {
    data: GiftProduct[], // data is shown if the gift slider is in use
    customize: GiftSliderCustomize
  },
  gifts_change: { // if the gift products change in cart
    add: GiftChangeAdd[], // if the gift is not in cart => automatically added
    update: GiftChangeUpdate[] // if the gift is already in cart => quantity will be change automatically
  },
  codes?: string[], // this field is shown if the discount code is used to discount gift product
  cart_message: {
    data: CartMessage[], // if the cart message is in use
    customize: CartMessageCustomize
  },
  today_offers: {
    data: TodayOffer[],  // list of currently available offers on the store
    customize: TodayOfferCustomize
  }
}

2. Use response data to display gift in sale channels

The response data, including gift product ID, will be used to display gifts in the sale channels.

• For the gift that is automatically added to the customer's cart, refer to the field “gift_change:” in Response. See how to use StorefrontAPI to add gift to cart, remove gift from cart here

• For the gift will be displayed in the slider for customers’ selection, refer to the field “popup:” in Response.

Example of gift slider displayed in storefront

STEP 2: /api-partner/products-sync-quantity

Fetching information on the gift products to verify quantities (only necessary if the 'Settings: Sync-quantity' feature is enabled).

Sync quantity Integration flow

About Sync quantity Integration flow:

Once the user posts /api-partner/products-sync-quantity, the response contains the list of productIDs that need to be verified for the quantity level.

Users can use Storefront API to get the quantity level of those products. Example here.

Then post /api-partner/bogos with eligible product data

• Params

{
   shop: string; // myshopify domain
}

• Body

{
   shop: string; // myshopify domain
}

• Response

ProductSyncQuantity[]

For partners and users integrated before Nov 6, 2024. It is required to update the integrations with those fields:

• codes?: string[], // this field is shown if the discount code is used to discount gift product

• properties?: { //properties are used to define which item is gift 
      _bogos_trigger_id: string; 
      _bogos_trigger: string;
      _bogos_trigger_type: string;
  }

STEP 3: /api-partner/gift-customize

Return the customization to the Gift-icon, product page message, and gift products for buying specific products or variants.

• Body

{
  shop: string; // myshopify domain

  products: ProductInfo[];
  
  productsQuantity?: ProductInfo[];

  customer?: Customer; // required if sub-condition with customer information is in use

  other?: OtherParams;
}

• Response

{
  data: ProductHasGifts[]; // return all products from request body
  // if a gift product is associated with purchasing that product,
  //data will be generated 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;
      };
    };
  };
}