--- title: 'shopify:cart:lines-update' description: 'Fires when cart lines are added, updated, or removed.' source_url: html: >- https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-lines-update md: >- https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-lines-update.md api_name: storefront-events-and-actions --- # shopify:cart:lines-update Fires when a buyer adds, removes, or updates cart lines. One event covers all three, and the `action` field tells you which. The `context` field tells you where it came from, with `product`, `cart`, or `dialog` for a buyer's own interaction, and `standard-action` when an [`updateCart`](https://shopify.dev/docs/api/storefront-events-and-actions/actions/update-cart) call emitted it. This is the signal that a cart changed, and it replaces watching the DOM or intercepting cart requests. The event fires before the cart is updated, so listeners can show a loading or optimistic state while the operation runs. You dispatch it from the cart element, or from the product element for adds on a product 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. #### Properties * **action** **'add' | 'remove' | 'update'** **required** Whether the lines were added, updated, or removed. This value determines the shape of `lines`. * **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. * **lines** **CartLinesUpdateLine\[]** **required** The cart lines that changed. Contains at least one entry. * **promise** **Promise\** **required** Resolves with a `CartLinesUpdateResult` when the update finishes. It rejects if the request fails or is aborted, such as on a network error or when a newer update supersedes it. * **detail** **Record\** Optional custom data for the storefront's internal use. Listeners can read it. ### CartLinesUpdateLine A single line in a \`shopify:cart:lines-update\` payload. Which identifier you use depends on \`action\`. * merchandiseId The product variant to add. Required when \`action\` is \`add\`. Accepts a number, a string, or a full GID string. ```ts string ``` * id The cart line to change. Required when \`action\` is \`remove\` or \`update\`. Accepts a number, a string, or a full GID string. ```ts string ``` * quantity The quantity for the line. ```ts number ``` ### CartLinesUpdateResult The value that the \`promise\` field of a \`shopify:cart:lines-update\` event resolves with. Check \`userErrors\` and \`warnings\` before you read \`cart\`. * cart The cart after the mutation, or \`null\` if no cart exists. ```ts StandardEventCart | null ``` * userErrors Validation errors returned by the cart mutation. ```ts CartMutationUserError[] ``` * warnings Non-blocking warnings returned by the cart mutation. ```ts CartMutationWarning[] ``` * detail Custom data from whichever code resolved the promise. ```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 { CartLinesUpdateEvent } from '@shopify/standard-events'; const deferred = CartLinesUpdateEvent.createPromise(); element.dispatchEvent( new CartLinesUpdateEvent({ action: 'add', context: 'product', lines: [{ merchandiseId: variantId, quantity: 1 }], promise: deferred.promise, }), ); await fetch(`${window.Shopify.routes.root}cart/add.js`, { method: 'POST', headers, body, }); const ajaxCart = await fetch(`${window.Shopify.routes.root}cart.js`).then( (response) => response.json(), ); deferred.resolve({ cart: CartLinesUpdateEvent.createCartFromAjaxResponse(ajaxCart), }); ``` * #### ##### Listen for the event ```javascript document.addEventListener('shopify:cart:lines-update', (event) => { if (event.action === 'add') { console.log('Added', event.lines); } event.promise.then(({ cart }) => updateCartCount(cart?.totalQuantity)); }); ``` ***