shopify:cart:error

Fires when a cart operation fails, such as an add to cart that the cart rejects.

You can use this to tell a failure from an operation that's still running, so an optimistic update rolls back rather than staying on screen.

You dispatch it from the same element as the operation that failed. Without an eventTarget, an action dispatches it from document.

This event reaches every listener, which is how an app learns about a failure it didn't cause. It fires only when the request itself failed, and the promise of that operation rejects at the same time. A cart that declines a change isn't a failure: the promise resolves with userErrors and no error event.

Anchor to propertiesProperties

Anchor to error error string required: A human-readable message describing what failed. Don't parse this. Branch on code instead.
Anchor to code code required: The reason the operation failed. Branch on this rather than on error.
Anchor to detail detail Record<string, unknown>: Optional custom data for the storefront's internal use. Listeners can read it.

CartErrorCode

The reason a cart operation failed. These values match the Storefront API [`CartErrorCode`](/docs/api/storefront/latest/enums/CartErrorCode) enum.

'ADDRESS_FIELD_CONTAINS_EMOJIS' | 'ADDRESS_FIELD_CONTAINS_HTML_TAGS' | 'ADDRESS_FIELD_CONTAINS_URL' | 'ADDRESS_FIELD_DOES_NOT_MATCH_EXPECTED_PATTERN' | 'ADDRESS_FIELD_IS_REQUIRED' | 'ADDRESS_FIELD_IS_TOO_LONG' | 'BUNDLES_AND_ADDONS_CANNOT_BE_MIXED' | 'BUYER_CANNOT_PURCHASE_FOR_COMPANY_LOCATION' | 'CART_TOO_LARGE' | 'GIFT_CARD_RECIPIENT_INVALID' | 'INVALID' | 'INVALID_COMPANY_LOCATION' | 'INVALID_DELIVERY_ADDRESS_ID' | 'INVALID_DELIVERY_GROUP' | 'INVALID_DELIVERY_OPTION' | 'INVALID_INCREMENT' | 'INVALID_MERCHANDISE_LINE' | 'INVALID_METAFIELDS' | 'INVALID_ZIP_CODE_FOR_COUNTRY' | 'INVALID_ZIP_CODE_FOR_PROVINCE' | 'LESS_THAN' | 'MAXIMUM_EXCEEDED' | 'MERCHANDISE_NOT_APPLICABLE' | 'MINIMUM_NOT_MET' | 'MISSING_CUSTOMER_ACCESS_TOKEN' | 'MISSING_DISCOUNT_CODE' | 'MISSING_NOTE' | 'NOTE_TOO_LONG' | 'ONLY_ONE_DELIVERY_ADDRESS_CAN_BE_SELECTED' | 'PARENT_LINE_INVALID_REFERENCE' | 'PARENT_LINE_NESTING_TOO_DEEP' | 'PARENT_LINE_NOT_FOUND' | 'PARENT_LINE_OPERATION_BLOCKED' | 'PENDING_DELIVERY_GROUPS' | 'PROVINCE_NOT_FOUND' | 'SELLING_PLAN_NOT_APPLICABLE' | 'SERVICE_UNAVAILABLE' | 'TOO_MANY_DELIVERY_ADDRESSES' | 'UNSPECIFIED_ADDRESS_ERROR' | 'VALIDATION_CUSTOM' | 'VARIANT_REQUIRES_SELLING_PLAN' | 'ZIP_CODE_NOT_SUPPORTED'

Examples

Dispatch the event

import { CartErrorEvent } from '@shopify/standard-events';

element.dispatchEvent(

new CartErrorEvent({

error: 'Only 3 left in stock.',

code: 'MAXIMUM_EXCEEDED',

}),

);

Examples

Dispatch the event

import { CartErrorEvent } from '@shopify/standard-events';

element.dispatchEvent(
  new CartErrorEvent({
    error: 'Only 3 left in stock.',
    code: 'MAXIMUM_EXCEEDED',
  }),
);

Listen for the event

document.addEventListener('shopify:cart:error', (event) => {
  if (event.code === 'MAXIMUM_EXCEEDED') {
    showMessage(event.error);
    return;
  }

  showMessage('Something went wrong. Try again.');
});

Was this page helpful?