BOGOS API INTEGRATION

OVERVIEW

Install app: https://apps.shopify.com/freegifts

Url API integration: https://api.freegifts.io/

If you need integration in development environment, contact via live chat or email us at [e-mail]

After creating/editing the offer, please ensure that the gift/cloned product is available on the storefront channel for the offer to work.

Hide gift product (cloned product) by tag: "bogos-gift" or handle: "*-sca_clone_freegift"

DEFAULT TYPE

export type OtherParams = {
  languageCode?: string;
  countryCode?: string; // sub-condition: customer location.
  toFixed?: number;     // toFixed with count-down cart message(default: 2). 
                        // E.g: Spend $100.00 get X.  
  enableForAllCondition?: boolean; // enable customize:gift-icon for all main conditions
  fgCodes?: string[];   // sub-condition: specific link
  isMobileApp?: boolean; // fill value "true" if is a mobile app
};

export type BaseObj = {
  id: number;
  title: string;
};

export type CartItem = {
  id: string;
  variant_id: number;
  product_id: number;
  product_title: string;
  handle: string;
  vendor: string;
  product_type: string;
  collections: BaseObj[];
  price: number;
  compare_at_price?: number;
  quantity: number;
  selling_plan_allocation?: {
    selling_plan?: {
      id?: string;
      name?: string;
    };
  };
  currency?: string;
  tags: string[];
  properties: CartItemProperties[];
};

export type CartItemProperties = {
  key: string;
  value: string;
}

export type GiftSliderCustomize = { // In-app -> Customize -> Gift slider
  general: {
    gift_popup_title: string;
    add_to_cart_btn_title: string;
    running_text: string;
    select_gift_btn: string;
    show_product_title: boolean;
    show_variant_title: boolean;
    show_pagination: boolean;
    show_gift_for_customer: ShowGiftsBy;
    number_product_slider: number;
  };
  color: {
    gift_slider_title_color: string;
    product_title_color: string;
    original_price_color: string;
    discounted_price_color: string;
    add_to_cart_color: string;
    add_to_cart_btn_color: string;
  };
  others: {
    hidden_brand_mark: boolean;
    gift_img_size: string;
  };
  disable_slider_checkbox: {
    enable: boolean;
    time: number;
    text: string;
  };
};

export type FilterVariant = {
  id: string | number;
  title: string;
  price?: string | number;
  available?: boolean;
};

export type ProductInfo = {
  id: string | number;
  handle: string;
  title: string;
  price_max: number;
  collections: {
    id: number;
    title?: string;
  }[];
  product_type: string;
  vendor: string;
  variants: FilterVariant[];
  variants_quantity?: { // required if settings:sync-quantity is in use
    [key: number]: number;
  };
};

export type Customer = {
  tags?: string[];
  email?: string;
  orders_count?: number;
  total_spent?: number;
  orders_history?: OrderHistory[];
};

export type OrderItem = {
  quantity: number;
  title: string;
  price: number;
  discount_allocations?: {
    amount: number;
    title?: string;
    code?: string;
  }[];
  variant?: {
    id: string;
    price: number;
    title: string;
    product?: {
      id: string;
      handle: string;
      tags: string[];
      title: string;
    };
  };
};

export type OrderHistory = {
  financial_status: string;
  fulfillment_status: string;
  id: string;
  total_price: number;
  created_at: string;
  items: OrderItem[];
};

export 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;
  properties?: {                 //properties are used to define which item is gift 
    _bogos_trigger_id: string; 
    _bogos_trigger: string;
    _bogos_trigger_type: string;
  }
};

export type GiftProduct = {
  id: number;
  title: string;
  handle: string;
  thumbnail?: string;
  belongs_to_offer: string;
  code?: string;  //this field is shown if the discount code is used to discount gift product
  variants: GiftItem[];
};

export type GiftChangeAdd = {
  variant_id: number;
  belongs_to_offer: string;
  quantity: number;
  properties?: {                 //properties are used to define which item is gift      
    _bogos_trigger_id: string;
    _bogos_trigger: string;
    _bogos_trigger_type: string;
  }
};

export type GiftChangeUpdate = GiftChangeAdd & {
  id: string;
};

export type CartMessage = {
  value: string;
  offer_root: string;
}

export type CartMessageCustomize = { // In-app -> Customize -> Cart message
  show_on_cart_page: boolean;
  text_color: string;
  background_color: string;
}

export type OfferCondition = {
  min_amount: number;
  max_amount: number;
  unit: string;
}

export type TodayOffer = {
  id: string;
  title: string;
  gifts: GiftProduct[];
  offer_conditions: OfferCondition[];
  success: boolean;
}

export type TodayOfferCustomize = { // In-app -> Customize -> Today offer
  widget_icon: string;
  show_widget: boolean;
  widget_position: 'bottom_left' | 'bottom_right';
  widget_title: string;
  widget_subtitle: string;
  widget_icon_style: 'icon' | 'icon_and_title'; // Default: 'icon'
  icon_widget_title: string;
  widget_color?: {
    body_background_color: string; // '#FFFFFF';
    header_background_color: string; //'#FFFFFF';
    offer_default_color: string; //'#ebe9f1';
    offer_success_color: string; //'#69CE82';
    offer_title_color: string; //'#82868b';
    widget_subtitle_color: string; //'#b9b9c3';
    widget_title_color: string; //'#5E5873';
  };
}

export type ProductHasGifts = {
  variants_has_gift?: { // receive gifts associated with each variant
    [key: number]: GiftProduct[];    
  };
  gifts_will_receive: GiftProduct[];  // receive gifts associated to each products 
                                      // (apply to all product variants)
  info: ProductInfo;  
  offers_has_gifts: {
    id: number; // offer id
    name: string;
    offer_root: number;
    start_time: string | Date;
    end_time: string | Date;
    priority: number;
    gift_thumbnail_items_filter: GiftProduct[]
  }[];
}

export type ProductSyncQuantity = {
  id: number;
  handle: string;
  variants: number[];
}

// For classic bundle
export type DiscountBasicBundle =  {
  type: "percentage" | "fixed_amount";
  value: number;
}

// Except classic bundle
export type DiscountAdvanceBundle = {
  id: string;
  title: string;
  discount: DiscountBasicBundle;
  label?: string;
  tag?: string;
  quantity: number;
  pre_selected?: boolean; // Only use in quantity break bundle
}

export enum BundleType {
  CLASSIC = 'classic_bundle',
  QUANTITY_BREAK = 'quantity_break',
  MIX_MATCH = 'mix_match',
  BUNDLE_PAGE = 'bundle_page',
}

export type ProductsConditionBundle = {
  type: "variants_ids" | "product_collection" 
        | "product_types" | "product_vendors" | "config";
  value: ProductInfo[] 
        | { [key: string]: any }[] 
        | { 
            mix_type: "diff_set" | "single_set", 
            mix_items: {id: number, min_quantity: number }[]
          };
}

export type Bundle = {
  id: string;
  shop_id: string;
  title: string;
  sub_title?: string;
  code: string;
  label?: string;
  description?: string;
  start_time: string | Date;
  end_time?: string | Date;
  status: boolean;
  products: ProductsCondition[];
  discount: DiscountAdvanceBundle[] | DiscountBasicBundle;
  type: BundleType;
  shopify_discount_settings: {
    {
      combinations: {
        order: boolean, 
        product: boolean, 
        shipping: boolean
      }
   }
  };
}
 

MIDDLEWARE

Add this header for authorization.

• Header

{
   authorization: "Bearer $token",
   verify: ""; //contact bogos for help
}

• How to get $token (using https://www.npmjs.com/package/jsonwebtoken)

const jwt = require('jsonwebtoken');

const payload = {
  integration: "" //contact bogos for help
};

const secretKey = 'secret_key'; //contact bogos for secret_key
const token = jwt.sign(payload, secretKey, {expiresIn: 120});

I. POST: /api-partner/bogos

Handle the main logic of BOGOS related to gift products (including add, update/remove, or display gift slider).

Additionally, there is information related to customizing the Cart-message and Today-offer widget.

• 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
  }
}

II. POST: /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;
      };
    };
  };
}

III. POST: /api-partner/products-sync-quantity

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

• 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;
  }

IV: POST: /api-partner/bogos/bundle

Fetching bundles active belongs to products.

• Body

{
   shop: string; // myshopify domain
   products: ProductInfo[];
   other?: OtherParams;
}

• Response

{
    data: {
        product_info: ProductInfo;
        bundles: Bundle[]
    }[]
}