Storefront APIs - Imperative APIs

Configuration can take you a long way with Salesforce Commerce Cloud, all from what products show up in your store to what the branding of the page looks like. There typically is a point though where some level of customization is required, this means getting into code and building custom Lightning Web Components. That's where Storefront APIs come into the picture.

This article starts a 3 part series where we'll go through each Storefront API and provide examples, the three Storefront APIs are:

1. Imperative API (This article)

2. Wire Adapter

3. Storefront Action

Before we get going though, you might be asking "Why do I need Storefront APIs? I can just use Apex to modify the raw data however i'd like!". Well you're not wrong, however by not using these Storefront APIs you're incurring more technical debt then needed, slowing down your performance, and potentially even opening up your store to access issues.

Using Storefront API provide these benefits (as well as more, but these are the most important):

1. Salesforce Best Practice

2. Performance

3. Lower Effort

Before jumping in, if you'd prefer watching this content, you can view a video on Salesforce Mojo.

Imperative API

"Imperative APIs are process-oriented functions that, for example, call a Connect API method (POST, PUT, PATCH) to update data and return an outcome. Imperative calls typically retrieve hosted data when triggered by a page load or button click. Imperative APIs prompt updates to related entities including Wire Adapters, all orchestrated via State Management."

https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-display-lwc-apis.html#imperative-apis

When i'm developing a custom component one of the first things I do is research what Storefront APIs are available for my specific use case. At the time of writing this article there are the following bundles that can be used, each having at least 1 Imperative API that can be used in that type of experience.

• activitiesApi

• cartApi

• checkoutApi

• contextApi

• myAccountApi

• orderApi

• cmsEditorApi

• effectiveAccountApi

Imperative APIs allow you to easily make changes to the section of the store you're customizing, allowing you to focus on the presentation to the customer without having to write complex backend code that needs to handle every possible situation you need.

One use case is adding a product to your cart, something that natively the platform does, but for some businesses you may need to customize or add add to cart actions elsewhere in the experience. If you'd like to follow along in the example, you can find the Add To Cart component in the Code It Forward repository. https://github.com/commerce-codeitforward/Components-For-Salesforce-Commerce-Cloud/tree/main/product/addToCart

Importing the Imperative APIs

First, we need to import the APIs so we can call them inside our component. You can do that by adding these two lines to the top of our new component.

import { addItemToCart } from 'commerce/cartApi';
import { trackAddProductToCart } from 'commerce/activitiesApi';

Calling the Imperative APIs

Next, we are going to first call the addItemToCart API which is responsible for actually adding the item to the cart or returning an error if something goes wrong.

In this situation, we've chained the trackAddProductToCart API to the success of addItemToCart. This API is responsible for telling the storefront and data services that a new product has been added to the cart and it should refresh it's local store. This in essence updates the badge number in the cart icon at the top, and also updates the cart page without having to hard refresh the browser.

addItemToCart(this.productId, this.quantity)
	.then((data) => {
		if (data) {
			// this will update the cart and Cart icon.
			trackAddProductToCart(
				this.productId
			);
		}
})

If you're following along with the sample component, you'll want to place this new component on the Product page in your experience builder. Once you publish it, your store should look something like the below (with the red section being the component).

Add To Cart Component

Now let's test it! If you' like to see what happens behind the scenes for one of these Imperative APIs, you can open up your developer console on your browser and navigate over to the Network tab.

Once you've clicked the button, you will see two requests show up:

cart-items

This request is the response from the cart badge & cart summary data. In this example my cart quantity went from 2 to 3, so in the quantity attribute it specifies that there are now 3 in the cart.

current

This request provides the full current payload of the cart, unlike the last one we mentioned, it isn't just this one items details included.

Add To Cart - Network Tab

Each Imperative API is slightly different in what parameters it accepts, and the expected response payload. As I mentioned before, it's strongly recommended to use these over customizing if at all possible!