Mastering Error Handling in Custom LWC Components for Commerce Cloud Checkout

This article is for those of us who work to customize Salesforce Commerce Cloud checkout. Customizing checkout is a fairly common activity; in the B2B world, no two checkout are alike (in most cases). We'll discuss commerce cloud error handling when building this customization.

In this article i'll talk about two concepts to help you along your journey of creating a great experience when things don't go quite right for the customer.

1. Handling Local Errors

2. Handling Global Errors

Scenario

Let's set the stage with an example to bring this to life. You've been given the requirement that all new addresses entered by the customer need to be validated to confirm they are shippable addresses. This validation has to happen with a 3rd party, let's say USPS / UPS / Vertex or something similar.

Due to the nature of this requirement, we'll need to build a custom LWC that allows a user to enter a new shipping address or add a new shipping address to their list of addresses. Either way, when a user enters an address we need to make an API call to validate that address and inform the user on the results, along with doing some validation along the way.

Now that we have the image in our mind, let's dive in.

Handling Local Errors

Having inline messaging and validation is a great way of alerting a user where the issue is they need to resolve. Using our address example, you should think about creating validation on each input that is required. For example, if I click into the address field and then leave that field without filling out the information you could put an error alert just around that field.

In our address example, another local error would be if the address comes back invalid, in that situation we'd want to inform the user of what the response from the API returned. In this situation it would most likely not be an inline error, but likely something at the top of the component to inform the user.

This is a fairly widely known approach when building custom component within and without the Salesforce ecosystem, I mention it in this blog to reinforce that this should be a practice that is followed when building commerce cloud components as well.

Handling Global Errors

In some situations you may need to alert a customer there is 'global' error, something that may prevent them from proceeding. Some examples of these may be:

• Their cart needs to be reviewed before proceeding

• There is a larger issue with their checkout session or checkout in general that is preventing

Out of the box, salesforce provides a notification component and a way to easily raise notifications to that global component. These notifications look like the following but the content will be what you decide to send in your component.

Within your component you're able to create and clear notifications from the global component, i'll provide an example of both in the following section. A little explanation on the values:

• groupId - This can be whatever value you want, but you need to use the same value between setting and clearing

• exception - This is the message you want to show to the user when this code is executed

Example of creating an error

this.dispatchUpdateErrorAsync({
	groupId: SHIPPING_ADDRESS_GROUP_CODE,
	type: '/commerce/errors/checkout-failure',
	exception: 'Sorry, we're having issues reaching the validation service right now.'
});

Example of clearing an error

this.dispatchUpdateErrorAsync({
	groupId: SHIPPING_ADDRESS_GROUP_CODE
});

Tip: I've found it's useful to wrap these two into their own functions so you can use them repeatedly throughout your component without having to paste the same block in multiple spots.

Ideally errors never happen, but in the situation where they do, it's a good practice to build fault tolerant code that can gracefully tell the user there is an issue going on or some piece of information they need to fix.