Storefront APIs - Storefront Actions

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

2. Wire Adapter

3. Storefront Action (This article)

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.

Storefront Actions

We come to the last topic in the available storefront api's, which is also the one that is most illusive as the documentation in how & what these are is pretty sparse as of writing this article.

I'm including below the only paragraph i've been able to pull from the Salesforce Commerce Cloud documentation.

Storefront Actions are events, such as adding an item to a cart or using a filter to search on a product variant, that trigger updates to closely-related LWCs. Unlike actual backend API endpoint communication, Storefront Actions react to UI clicks more responsively, by making changes to related page-level components in chain-of-sequence fashion within a proximate scope. When a customer clicks a quantity selector component, for example, a createCartItemsLoadAction refreshes the quantity displayed in the cart. Tight data binding ensures that the triggered operation gets and sets data from the closest source. That said, Storefront Actions can result in calls (via Wire Adapters or Imperative APIs) to Rest API endpoints

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

The above is a little window into what these actions are, but if you find yourself scratching your heads don't worry we'll be going through a handful of examples in this blog.

If you go to the storefront actions section of the above mentioned documentation, you'll notice there are plenty of actions that are available. On the surface, theses seem simple enough but if you've tried to use them in the past you'll find that you can't directly call them like you can with the imperative or wire functions.

Let's say you'd like to build a custom component on the cart page due to custom requirements for your storefront. This component would obviously need the cart items in order to show all the items on the page, so how would we accomplish this with storefront actions?

If we look to the documentation, the createCartItemsLoadAction action looks to be pretty promising in order to ensure we have loaded the full amount of our cart items. If we follow the documentation with the correct namespace, we'd think the import statement would look something like this:

import { createCartItemsLoadAction } from 'commerce/actionApi'; 

However, this will provide us a function that we won't be able to use by itself. Instead we need to import an additional function:

import { createCartItemsLoadAction, dispatchActionAsync } from 'commerce/actionApi';

You might be asking yourself.. what is a dispatch and why do I need it?

Dispatches

Let's talk about dispatches for a moment and define what is available and a description of how they can be used.

Name	Description	Available Page
dispatchUpdateAsync	Is used to update the Checkout Data Provider	Checkout
dispatchUpdateErrorAsync	Is used to notify checkout there is an error that needs to be presented (or cleared) to the user	Checkout
dispatchActionAsync	Is used to call one of the storefront api actions	Based on the Action type

Today, i'm not going to explain the first two dispatches as those aren't related to the topic of this article but I do plan to write an article on this in the future because it too is lacking in explanation.

Storefront Action Example

The example we'll use today will be the one I mention in my video, so if you haven't seen that yet now would be a good time!

Our use case is we'd like a button on the page that updated one of my cart items quantity from 1 to 2. In this situation i'm going to use the Storefront Action createCartItemUpdateAction but as I mentioned above I have to use the dispatchActionAsync function as a wrapper in order to call my action.

The below is how you'd properly call a Storefront Action:

await dispatchActionAsync(this, createCartItemUpdateAction('0a9DI0000000Si0YAE', 2));

(Note: this is an example so the values are hard coded, but in a real life scenario you'd want these to be dynamic based on the item the user clicks and have it increment up the quantity based on where the current amount was at)

In my sample component I walk through in the Storefront API video I use the following code which is called from an onClick event.

handleAddMoreButton() {
	this.requestMoreCartItems();
}

async requestMoreCartItems(){
     await dispatchActionAsync(this, createCartItemUpdateAction('0a9DI0000000Si0YAE', 2));
}

This action is powerful because it's going to not only update the cart item quantity, but it's also going to trigger a wire update since this is directly tied to the native hooks available. This will ensure that all the standard component are correctly updated as you make changes to the store data.

Wrap Up

Storefront Actions are powerful tools in your belt as you customize commerce cloud, and now that you understand how to properly call these actions they will allow you another tool to make a flexible commerce component.

Happy Coding!