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
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.
- 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.
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);