Guides

List of Available Utils Functions & Events

Supported scopes

SDK provides functions to allow developers to get storefront info easily, below provide a quick overview on the supported scope

a. Get current page, theme, loaded language, loaded currency

b. Get merchant ID, cookie consent

c. Get products (id, categoryIds, tags) | @ PLP & PDP page only

d. Get metafields value

e. Get order id | @ Order Confirm & Order Detail only

f. Get info of products | @ Order Confirm, Order Detail & Promotion Page only

g. Get shopping cart info | @ Cart & Checkout Page

h. Add, update quantity of, or remove products in the cart | @ pages with cart-mutation support enabled

Events

Following is a list of supported event topics for the SDK to listen to. For more information about event listeners, refer to here.

  • currency.changed
  • cart.update | @ PLP, PDP, Order Confirm page, Order Detail page, Cart page, Checkout Page
  • page.variationChanged | @ PDP page only
  • page.quantityChanged | @ PDP page only
  • page.addonQuantityChanged | @ PDP page only

Utils Functions

All functions listed here are async functions. Here are the list of supported utils functions:

  • getCurrentPageIdentifier()
  • getCurrentThemeKey()
  • getLoadedLanguage()
  • getLoadedCurrency()
  • getMerchantId()
  • getCookieConsent()
  • getPDPProduct()
  • getPLPProducts()
  • getMetafieldValues({ resource_type, resource_ids, keys })
  • getOCPOrder()
  • getOCPProducts()
  • getODPOrder()
  • getODPProducts()
  • getPPProducts()
  • getCPCartItems()
  • getCOPCartItems()
  • addCartItem({ product_id, variation_id, quantity, type, item_data, open_mini_cart })
  • addCartItems({ main_product_id, items, open_mini_cart })
  • updateCartItemQuantity({ item_id, quantity })
  • removeCartItem({ item_id })

Event Payload Reference Example

currency.changed

Return Value:

A string that represents the currency code.

Example Payload of the Event

sdk.events.addEventListener('currency.changed', (payload) => {
  console.log(payload);
  // Output: hkd
});

cart.update

Return Value:

An object including the latest information of the cart.

Example Payload of the Event

sdk.events.addEventListener('cart.update', (payload) => {
    console.log(payload);
    // Output: {
    //     "id_v2": "1317718",
    //     "owner_id": "664c73b22ffa7a00437addce",
    //     "owner_type": "User",
    //     "merchant_id": "6270db2f9ece2a1f1089d7ac",
    //     "items": [
    //         {
    //             "_id": "2033165",
    //             "product_id": "64f695ad931347370a5a96a4",
    //             "variation_id": "",
    //             "quantity": 1,
    //             ...
    //         },
    //         {
    //             "_id": "2033214",
    //             "product_id": "66589fb1e9bd62001fe9953b",
    //             "variation_id": "62d517722c015a00312c7df4",
    //             "quantity": 1,
    //             ...
    //         }
    //     ],
    //     ...
    // }
});

page.variationChanged

Triggered when the selected variation changes in PDP.

Return Value:

An object:

  • productId: A string of the main product ID.
  • variationId: A string of the selected variation ID.

Example Payload of the Event

sdk.events.addEventListener('page.variationChanged', (payload) => {
  console.log(payload);
  // Output: {
  //   "productId": "63bbbe56c1369e0039e5aa3c",
  //   "variationId": "62d517722c015a00312c7df4"
  // }
});

page.quantityChanged

Triggered when the main product quantity changes in PDP.

Return Value:

An object:

  • productId: A string of the main product ID.
  • variationId: A string of the selected variation ID (null if none selected).
  • quantity: A number of the current quantity.

Example Payload of the Event

sdk.events.addEventListener('page.quantityChanged', (payload) => {
  console.log(payload);
  // Output: {
  //   "productId": "63bbbe56c1369e0039e5aa3c",
  //   "variationId": null,
  //   "quantity": 2
  // }
});

page.addonQuantityChanged

Triggered when an add-on product quantity changes in PDP.

Return Value:

An object:

  • productId: A string of the add-on product ID.
  • variationId: A string of the add-on variation ID (null if none).
  • mainProductId: A string of the main product ID.
  • mainVariationId: A string of the main product's selected variation ID (null if none).
  • quantity: A number of the current add-on quantity.

Example Payload of the Event

sdk.events.addEventListener('page.addonQuantityChanged', (payload) => {
  console.log(payload);
  // Output: {
  //   "productId": "66589fb1e9bd62001fe9953b",
  //   "variationId": null,
  //   "mainProductId": "63bbbe56c1369e0039e5aa3c",
  //   "mainVariationId": "62d517722c015a00312c7df4",
  //   "quantity": 1
  // }
});


Utils Functions Reference Example

getCurrentPageIdentifier()

Get the current page identifier.

Available Pages: all

Return Value:

A string that represents the current page identifier.

Example

pageIdentifier = await sdk.utils.getCurrentPageIdentifier();

console.log(pageIdentifier);
// Output: home

getCurrentThemeKey()

Get merchant current theme key.

Available Pages: all

Return Value:

A string that represents the merchant current theme key.

Example

themeKey = await sdk.utils.getCurrentThemeKey();

console.log(themeKey);
// Output: ultra_chic

getLoadedLanguage()

Get current loaded language.

Available Pages: all

Return Value:

An object that represents the loaded language:

  • name: the name of the language (e.g. 繁體中文)
  • code: the code of the language (e.g. zh-hant)
loadedLanguage = await sdk.utils.getLoadedLanguage();

console.log(loadedLanguage);
// Output: {
//   "name": "繁體中文",
//   "code": "zh-hant"
// }

getMerchantId()

Get merchant ID.

Available Pages: all

Return Value:

A string that represents the merchant ID.

merchantId = await sdk.utils.getMerchantId();

console.log(merchantId);
// Output: 62958ab9a0883410b6a1c18f

getCookieConsent()

Get the current cookie consent.

Available Pages: all

Return Value:

An object that represents the cookie consents:

  • necessary: a boolean that represents if the user has agreed to necessary cookies.
  • statistical: a boolean that represents if the user has agreed to statistical cookies.
  • marketing: a boolean that represents if the user has agreed to marketing cookies.
  • functionality: a boolean that represents if the user has agreed to functionality cookies.

Example:

cookieConsents = await sdk.utils.getCookieConsent();

console.log(cookieConsents);
// Output: {
//    "necessary": true,
//    "statistical": true,
//    "marketing": true,
//    "functionality": true
//}

getLoadedCurrency()

Get the loaded currency.

Available Pages: all

Return Value:

A string that represents the loaded currency.

Example:

loadedCurrency = await sdk.utils.getLoadedCurrency();

console.log(loadedCurrency);
// Output: hkd

<details>
<summary>Click to expand</summary>

Your content here.

</details>

getPDPProduct()

Get product in Product Detail Page

Available page: Product Detail Page (product_detail)

Return Value:

An object that contains info of the product in the PDP:

  • main_product_id: A string that represents the (main) product ID
  • tags: A string that represents the tags of products, separated with ,
  • category_ids: An array of string that represents the IDs of categories of the product
  • variation_rendered: A boolean indicating whether the product has variations
  • variation_ids: An array of string of the product's variation IDs (null if no variation)
  • default_variation_id: A string of the variation ID matched from the URL variant_id (null if not matched)
  • id: (Deprecated) Same as main_product_id
  • variation_keys: (Deprecated, please use variation_ids instead.) An array of string of the product's variation IDs (empty array [] if no variation)
  • addon_product_rendered: A boolean indicating whether the product has add-on products
  • addon_product_ids: An array of string of the product's add-on product IDs (null if no add-on product)

Example:

product = await sdk.utils.getPDPProduct();

console.log(product);
// Output: {
//     "id": "63bbbe56c1369e0039e5aa3c",                  // Deprecated, same as main_product_id
//     "variation_keys": [                                 // Deprecated, same as variation_ids ([] if none)
//         "62d517722c015a00312c7df4",
//         "62d517722c015a00312c7df5"
//     ],
//     "main_product_id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31"
//     ],
//     "variation_rendered": true,
//     "variation_ids": [
//         "62d517722c015a00312c7df4",
//         "62d517722c015a00312c7df5"
//     ],
//     "default_variation_id": "62d517722c015a00312c7df4",
//     "addon_product_rendered": true,
//     "addon_product_ids": [
//         "66589fb1e9bd62001fe9953b",
//         "66589fb1e9bd62001fe9953c"
//     ]
// }
product = await sdk.utils.getPDPProduct();

console.log(product);
// Output: {
//     "id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31"
//     ]
// }

getPLPProducts()

Get products in Product Listing Page

Available page: Product Listing Page (product_list)

Return Value:

An array of objects that contains info of the products in the PLP:

  • id: A string that represents the product ID
  • tags: A string that represents the tags of products, separated with ,
  • category_ids: An array of string that represents the IDs of categories of the product

Example:

products = await sdk.utils.getPLPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31",
//         "6295b6664586dd003c1d89d8"
//     ],
//   }
// ]

getMetafieldValues({ resource_type, resource_ids, keys })

Get metafield values of supported resources

Available Page: all

Parameters:

  • resource_type: the supported resource type of metafields (e.g. product, customer, ...)
    • For customer, order, order_item types, you can only get the metafield values only when the user has logged in.
  • resource_ids: an array of string that represents the resource IDs of the metafield. For different resource type, you can input different length of resource IDs.
    • merchant, customer: You don't need to input this field
    • product: You can input multiple product IDs as the resource_ids. Max length is 72.
    • order, order_item: You can only input 1 order ID as the resource_ids
    • cart_item: You can input multiple identifiers as the resource_ids. Max length is 72.
      • For cart_item, the identifier is in the format of {cart_id}-{product_id}-{variation_id}
      • If the product does not contain a variation, the format would be {cart_id}-{product_id}
  • keys: an array of string that represents the metafields' keys

Return Value:

An object that contains the metafield values for each resource ID:

  • key: {resource_id}
  • value: An array of objects of metafields
    • namespace: namespace (i.e. app ID) of the metafield
    • key: key of the metafield
    • field_type: field_type of the metafield
    • field_value: field_value of the metafield

Example:

metafieldValues = await sdk.utils.getMetafieldValues(
  { resource_type: 'merchant', keys: ['example_key_1'] }
);

console.log(metafieldValues);
// Output: {
//   '63bbbe56c1369e0039e5aa3c': [		// resource ID
//     {
//       namespace: "62958abc38aec9003b96d538",		// app ID
//       key: "example_key_1",
//       field_type: "number_integer",
//       field_value: 100,
//     }
//   ]
// }

getOCPOrder()

Get order in Order Confirm Page

Available page: Order Confirm Page (order_confirm)

Return Value:

An object that contains info of the order in the OCP:

  • id: A string that represents the order ID

Example:

order = await sdk.utils.getOCPOrder();

console.log(order);
// Output: {
//   "id": "63bbbe56c1369e0039e5aa3c"
// }

getOCPProducts()

Get info of products in the order in Order Confirm Page

Available page: Order Confirm Page (order_confirm)

Return Value:

An array of objects that contains info of the products in that order in OCP:

  • id: A string that represents the product ID

Example:

products = await sdk.utils.getOCPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c"
//   }
// ]

getODPOrder()

Get order in Order Detail Page

Available page: Order Detail Page (order_detail)

Return Value:

An object that contains info of the order in the ODP:

  • id: A string that represents the order ID

Example:

order = await sdk.utils.getODPOrder();

console.log(order);
// Output: {
//   "id": "63bbbe56c1369e0039e5aa3c"
// }

getODPProducts()

Get info of products in the order in Order Detail Page

Available page: Order Detail Page (order_detail)

Return Value:

An array of objects that contains info of the products in that order in ODP:

  • id: A string that represents the product ID

Example:

products = await sdk.utils.getODPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c"
//   }
// ]

getPPProducts()

Get info of products of the promotion in Promotion Page

Available page: Promotion Page (promotion_page)

Return Value:

An array of objects that contains info of the products in the PP:

  • id: A string that represents the product ID
  • tags: A string that represents the tags of products, separated with ,
  • category_ids: An array of string that represents the IDs of categories of the product

Example:

products = await sdk.utils.getPPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31",
//         "6295b6664586dd003c1d89d8"
//     ],
//   }
// ]

getCPCartItems()

Get cart id and info of products in Cart Page

Available page: Cart Page (cart)

Return Value:

An object that contains info of the cart items in the CP:

  • id: A string that represents the cart ID
  • items: An array of objects that contains info of products in the cart for you to form the cart_item identifier

Example:

cartItems = await sdk.utils.getCPCartItems();

console.log(cartItems);
// Output: {
//   "id": "1309639",
//   "items": [
//     {
//       "product_id": "64f695ad931347370a5a96a4",
//       "variation_id": "",
//       "quantity": 1
//     },
//     {
//       "product_id": "64f695f99313475e7f5a9160",
//       "variation_id": "62d517722c015a00312c7df4",
//       "quantity": 2
//     }
//   ]
// }

getCOPCartItems()

Get cart id and info of products in Checkout Page

Available page: Checkout Page (checkout)

Return Value:

An object that contains info of the cart items in the COP:

  • id: A string that represents the cart ID
  • items: An array of objects that contains info of products in the cart for you to form the cart_item identifier

Example:

cartItems = await sdk.utils.getCOPCartItems();

console.log(cartItems);
// Output: {
//   "id": "1309639",
//   "items": [
//     {
//       "product_id": "64f695ad931347370a5a96a4",
//       "variation_id": ""
//     },
//     {
//       "product_id": "64f695f99313475e7f5a9160",
//       "variation_id": "62d517722c015a00312c7df4"
//     }
//   ]
// }

addCartItem({ product_id, variation_id, quantity, type, item_data, open_mini_cart })

Add a product to the cart.

Available page: pages with cart-mutation support enabled. Not available on the Cart, Checkout, or One Page Store pages (cart refresh is not yet reliable there), or on pages where the Storefront SDK itself is not loaded (Fast Checkout, Blog).

Parameters:

  • product_id: a string that represents the product ID (required)
  • variation_id: a string that represents the variation ID (required if the product has variations)
  • quantity: a number that represents the quantity to add, must be >= 1 (required)
  • type: a string that represents the product type. One of product (default), product_set, addon_product, subscription_product, redeem_gift (optional)
  • item_data: an object, required only when type is product_set. Contains selected_child_products — an array of objects, each with child_product_id, child_variation_id, quantity (optional)
  • open_mini_cart: a boolean that controls whether the mini-cart panel opens after a successful add. Defaults to true (optional)

Return Value:

An object that contains:

  • success: a boolean that represents whether the item was added

This function does not return the full cart. Subscribe to the cart.update event to get the latest cart content — each item in that payload has an id, which is the item_id required by updateCartItemQuantity/removeCartItem.

Example:

result = await sdk.utils.addCartItem({
  product_id: 'PRODUCT_ID',
  variation_id: 'VARIATION_ID',
  quantity: 1,
  open_mini_cart: false, // optional, defaults to true
});

console.log(result);
// Output: { success: true }

Errors:

The promise rejects with { success: false, message } if the request fails (e.g. insufficient stock, exceeded purchase limit).

addCartItems({ main_product_id, items, open_mini_cart })

Add a main product and one or more addon products to the cart in a single batch request. Use this instead of calling addCartItem multiple times when adding addon products, so the addon items correctly carry main_product_id.

Available page: pages with cart-mutation support enabled. Not available on the Cart, Checkout, or One Page Store pages (cart refresh is not yet reliable there), or on pages where the Storefront SDK itself is not loaded (Fast Checkout, Blog).

Parameters:

  • main_product_id: a string that represents the main product ID (required)
  • items: a non-empty array of objects, each with the same fields as addCartItem (product_id, variation_id, quantity, type, item_data). Does not need to include an entry for main_product_id (required)
  • open_mini_cart: same as addCartItem. Only takes effect when the main_product_id item is actually added (optional, defaults to true)

Return Value:

An object with success (boolean). Does not return the full cart — subscribe to cart.update for the latest cart content.

Example:

result = await sdk.utils.addCartItems({
  main_product_id: 'MAIN_PRODUCT_ID',
  items: [
    { product_id: 'MAIN_PRODUCT_ID', quantity: 1 },
    { type: 'addon_product', product_id: 'ADDON_PRODUCT_ID', quantity: 1 },
  ],
});

console.log(result);
// Output: { success: true }

Errors:

The promise rejects with { success: false, message } if the request fails (e.g. insufficient stock, exceeded purchase limit, an item entry is invalid).

updateCartItemQuantity({ item_id, quantity })

Update the quantity of a product already in the cart.

Available page: pages with cart-mutation support enabled. Not available on the Cart, Checkout, or One Page Store pages (cart refresh is not yet reliable there), or on pages where the Storefront SDK itself is not loaded (Fast Checkout, Blog).

Parameters:

  • item_id: a string that represents the cart item ID — this is the id of an item from the cart.update event payload, not the product_id (required)
  • quantity: a number that represents the new quantity. May be 0 — this removes the item from the cart (required)

Return Value:

An object with success (boolean). Does not return the full cart — subscribe to cart.update for the latest cart content.

Example:

result = await sdk.utils.updateCartItemQuantity({
  item_id: 'ITEM_ID',
  quantity: 3,
});

console.log(result);
// Output: { success: true }

Errors:

The promise rejects with { success: false, message } if the request fails (e.g. insufficient stock, exceeded purchase limit).

removeCartItem({ item_id })

Remove a product from the cart.

Available page: pages with cart-mutation support enabled. Not available on the Cart, Checkout, or One Page Store pages (cart refresh is not yet reliable there), or on pages where the Storefront SDK itself is not loaded (Fast Checkout, Blog).

Parameters:

  • item_id: a string that represents the cart item ID (same as above, required)

Return Value:

An object with success (boolean). Does not return the full cart — subscribe to cart.update for the latest cart content.

Example:

result = await sdk.utils.removeCartItem({
  item_id: 'ITEM_ID',
});

console.log(result);
// Output: { success: true }

Errors:

The promise rejects with { success: false, message } if the request fails.

Updated 13 days ago