Frontend API

The Frontend API is a set of convenient functions that you can use in your frontend to get product and price information, trigger price rule evaluations, and debug the general behavior of Price Rules in your store. The API for frontend interaction is available in window.BOLD.pre.

Prerequisites

Before you get started, review the appropriate page in the Storefront Setup section for implementation instructions depending on the shops platform. Note that Frontend API is not available for headless implementations using our headless endpoints.

async ready

note

This is the preferred way of accessing the Price Rules frontend API.

This also allows API calls to work in cases where the Price Rules build needs to be loaded onto the page asynchronously. Price Rules will call anything bound through this function when the API is ready on the page.

window.BOLD.pre.ready().then((api) => {
  api.setConfig({
    qty_breaks_show_single: false,
    shopify_auto_update_qty: false,
  });
});

events

api.events.on("update", () => {
  // something was updated
});

Event	Emitted when
update	Something was updated. Fired on all state changes or re-calculations.

async processCart

• Applies price rules adjustments to a cart in isolation from the main state of the page.
• Can be used to support custom theme display logic.
• Will result in a network call unless the products in the provided cart have previously been processed on this page.
• This method is asynchronous (returns a Promise).

api
  .processCart({
    token: "0a6d78aa07284fd13494060185090eb4",
    items: [
      {
        id: 17361703469115,
        properties: null,
        quantity: 1,
        variant_id: 17361703469115,
        key: "17361703469115:7f3bfe9d0d77424a0e3d4b9cf86ffe2f",
        title: "Real Goat",
        price: 15000,
        original_price: 15000,
        line_price: 15000,
        original_line_price: 15000,
      },
    ],
  })
  .then((cart) => {
    console.log("Updated cart!", cart);
  });

async processCartItem

• Applies price rules adjustments to a cartItem in isolation from the main state of the page.
• Can be used to support custom theme display logic.
• Will result in a network call unless the products in the provided cart have previously been processed on this page.
• This method is asynchronous (returns a Promise).

api
  .processCartItem({
    id: 17361703469115,
    properties: null,
    quantity: 1,
    variant_id: 17361703469115,
    key: "17361703469115:7f3bfe9d0d77424a0e3d4b9cf86ffe2f",
    title: "Real Goat",
    price: 15000,
    original_price: 15000,
    line_price: 15000,
    original_line_price: 15000,
  })
  .then((cartItem) => {
    console.log("Updated cart item!", cartItem);
  });

processCartSync

This is a synchronous version of processCart.

This function has the same usage characteristics except for that it is synchronous. It can therefore only consider rules that have already been loaded on the page.

This is important to consider because if you pass a cart with products not already represented on the page then those products will not receive their proper discounts.

const cart = api.processCartSync({
  token: "0a6d78aa07284fd13494060185090eb4",
  items: [
    {
      id: 17361703469115,
      properties: null,
      quantity: 1,
      variant_id: 17361703469115,
      key: "17361703469115:7f3bfe9d0d77424a0e3d4b9cf86ffe2f",
      title: "Real Goat",
      price: 15000,
      original_price: 15000,
      line_price: 15000,
      original_line_price: 15000,
    },
  ],
});
console.log("Updated cart!", cart);

processCartItemSync

This is a synchronous version of processCartItem.

const cartItem = api.processCartItemSync({
  id: 17361703469115,
  properties: null,
  quantity: 1,
  variant_id: 17361703469115,
  key: "17361703469115:7f3bfe9d0d77424a0e3d4b9cf86ffe2f",
  title: "Real Goat",
  price: 15000,
  original_price: 15000,
  line_price: 15000,
  original_line_price: 15000,
});
console.log("Updated cart item!", cacartItemrt);

getPriceByProductId

Gets Price Rules price for a certain product by product id.

api.getPriceByProductId(1784032362555);

formatAmount

Formats a price integer for display: 500 => "$5.00"

api.formatAmount(500);

setCurrency

Sets the storefront currency (ie. 'USD', 'CAD')

api.setCurrency("CAD");

removeCurrencyData

Remove the storefront Price Rules currency data from LocalStorage.

api.removeCurrencyData();

getProductByVariantId

Gets Price Rules state for a certain product by variant id.

api.getProductByVariantId(17361703469115);

getProductById

Gets Price Rules state for a certain product by its id.

api.getProductById(1784032362555);

getCartItem

Gets Price Rules state for a certain cart item by its line index or line id.

api.getCartItem(0);

getCart

Gets Price Rules state for the cart.

api.getCart();

async addProductJson

Add a single product to the Price Rules system. This call has the same effect as adding a .bold-product-json element into the page.

note

• For better performance while adding multiple products the below call to addProductsJson should be used. This will allow Price Rules to chunk requests for rules.
• The payload for the below example is reduced to only the required info. Passing the full product payload would also be fine (i.e. as received from the Shopify AJAX API product.js endpoint).

api
  .addProductJson({
    id: 1980128231510,
    variants: [
      {
        id: 19625793749078,
        price: 30400,
      },
    ],
  })
  .then((product) => {
    console.log("Discounted product", product);
  });

async addProductsJson

Add multiple products to the Price Rules system.

Notice: This function expects an array of product objects.

api
  .addProductsJson([
    {
      id: 1980128231510,
      variants: [
        {
          id: 19625793749078,
          price: 30400,
        },
      ],
    },
  ])
  .then((products) => {
    console.log("Discounted products", products);
  });

updateCustomer

Allows a customer update based on the current customer.

note

This method will update Price Rules state and could therefore affect discounts in other areas of the page.

api.updateCustomer((customer) => {
  customer.province = "MB";
  return customer;
});

hi

Visibly flashes Price Rules elements on the page. For debugging purposes.

api.hi();

elementReport

Provides details about the provided DOM element. Should be passed an HTMLElement instance of a Price Rules money element.

api.elementReport($0);