--- title: 'shopify:cart:attributes-update' description: Fires when the cart attributes change. source_url: html: >- https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-attributes-update md: >- https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-attributes-update.md api_name: storefront-events-and-actions --- # shopify:cart:attributes-update Fires when a buyer or an app sets or clears cart attributes. Cart attributes are key-value pairs on the cart, separate from attributes on cart lines, used for delivery dates and gift options. You can use this to keep your own copy of the attributes in sync, or to react when an attribute your app owns changes. `attributes` is the complete set the cart should end up with, replacing the existing set rather than merging with it, so send every key the cart should keep. Leaving out an existing key removes it, and an empty array clears all attributes. You dispatch it from the element holding the attribute fields, in the cart drawer or on the cart page. Because the event fires when the operation starts, it fires whether or not the change succeeds. If the cart declines the change, the promise resolves with the cart as it stands and `userErrors` explaining why. If the request fails, the promise rejects and [`shopify:cart:error`](https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-error) is dispatched. The resolved cart doesn't include attributes. When the promise resolves without `userErrors`, the event's `attributes` is the set the cart saved, so you can apply it to your UI when you dispatch, and revert it if the promise rejects or resolves with `userErrors`. #### Properties * **context** **'product' | 'cart' | 'dialog' | 'standard-action'** **required** Where the update came from. The `standard-action` value is reserved for events that [standard storefront actions](https://shopify.dev/docs/api/storefront-events-and-actions/actions) emit automatically. * **attributes** **CartAttributeInput\[]** **required** The complete set of cart attributes the cart should end up with. This replaces the existing attributes rather than merging with them, so leaving out an existing key removes it and an empty array clears them all. * **promise** **Promise\** **required** Resolves with a `CartAttributesUpdateResult` when the update finishes. It rejects if the request fails or is aborted. * **detail** **Record\** Optional custom data for the storefront's internal use. Listeners can read it. ### CartAttributeInput A custom key-value pair for a cart or cart line. * key The attribute's key. ```ts string ``` * value The attribute's value. ```ts string ``` ### CartAttributesUpdateResult The value a \`shopify:cart:attributes-update\` promise resolves with. * cart The cart after the attributes were saved. It doesn't include attributes; read the event's \`attributes\` for the set the cart saved. ```ts StandardEventCart | null ``` * userErrors Validation errors from the mutation. ```ts CartMutationUserError[] ``` * warnings Non-blocking warnings from the mutation. ```ts CartMutationWarning[] ``` * detail Optional custom data for the storefront's internal use. Listeners can read it. ```ts Record ``` ### StandardEventCart A subset of the \[Storefront API Cart object]\(/docs/api/storefront/latest/objects/Cart) that cart events carry. * id The cart GID. ```ts string ``` * totalQuantity The total number of items in the cart. ```ts number ``` * cost The total cost of the cart. ```ts StandardEventCartCost ``` * lines The lines in the cart. ```ts StandardEventCartLine[] ``` * discountCodes The discount codes on the cart. ```ts StandardEventCartDiscountCode[] ``` ### StandardEventCartCost The cost of a cart or a cart line. * totalAmount The total amount. ```ts MoneyV2 ``` ### MoneyV2 An amount with its currency, matching the Storefront API \[\`MoneyV2\`]\(/docs/api/storefront/latest/objects/MoneyV2) format. * amount A decimal money amount, such as \`29.99\`. ```ts string ``` * currencyCode The three-letter currency code, such as \`USD\`. ```ts string ``` ### StandardEventCartLine A single line in the cart. * id The cart line ID. A storefront on the AJAX cart API passes its own line keys through, so don't assume a GID. ```ts string ``` * quantity The quantity of merchandise on the line. ```ts number ``` * cost The cost of the line. ```ts StandardEventCartCost ``` ### StandardEventCartDiscountCode A discount code on the cart. * code The discount code the buyer entered. ```ts string ``` * applicable Whether the discount code applies to the cart. ```ts boolean ``` ### CartMutationUserError A validation error returned by a cart mutation. * code A machine-readable error code, such as \`INVALID\` for a malformed input or \`MAXIMUM\_EXCEEDED\` for a quantity above the item's maximum. See \[\`CartErrorCode\`]\(/docs/api/storefront/latest/enums/CartErrorCode) for the full list. ```ts string ``` * field The path to the field that caused the error. ```ts string[] ``` * message A human-readable message. ```ts string ``` ### CartMutationWarning A non-blocking warning returned by a cart mutation. * code A machine-readable warning code, such as \`MERCHANDISE\_OUT\_OF\_STOCK\` for a line whose merchandise ran out or \`MERCHANDISE\_NOT\_ENOUGH\_STOCK\` when only part of the requested quantity is available. See \[\`CartWarningCode\`]\(/docs/api/storefront/latest/enums/CartWarningCode) for the full list. ```ts string ``` * message A human-readable message. ```ts string ``` * target The cart line or field the warning applies to. ```ts string ``` Examples ### Examples * #### ##### Dispatch the event ```javascript import { CartAttributesUpdateEvent } from '@shopify/standard-events'; const attributes = [{ key: 'delivery_date', value: deliveryDateInput.value }]; const deferred = CartAttributesUpdateEvent.createPromise(); element.dispatchEvent( new CartAttributesUpdateEvent({ context: 'cart', attributes, promise: deferred.promise, }), ); const ajaxCart = await saveAttributes(attributes); deferred.resolve({ cart: CartAttributesUpdateEvent.createCartFromAjaxResponse(ajaxCart), }); ``` * #### ##### Listen for the event ```javascript document.addEventListener('shopify:cart:attributes-update', (event) => { renderAttributes(event.attributes); event.promise .then(({ userErrors }) => { if (userErrors?.length) { revertAttributes(); } }) .catch(revertAttributes); }); ``` ***