--- title: updateCart description: >- Adds, updates, or removes cart lines, sets the note, and applies discount codes. source_url: html: >- https://shopify.dev/docs/api/storefront-events-and-actions/actions/update-cart md: >- https://shopify.dev/docs/api/storefront-events-and-actions/actions/update-cart.md api_name: storefront-events-and-actions --- # update​Cart Adds, updates, or removes cart lines, sets the cart note, and applies discount codes. A single call can do more than one of these. You can use this instead of posting to the cart yourself, so your app doesn't need to know how the cart is rendered. A storefront that [configures](https://shopify.dev/docs/api/storefront-events-and-actions/actions/configure) this action refreshes its own UI. Without a configuration, the default refreshes the cart on [themes it recognizes](https://shopify.dev/docs/api/storefront-events-and-actions/actions/configure#how-the-defaults-recognize-a-theme), and reloads the page on themes it doesn't. A line with `merchandiseId` is an add, a line with `id` is an update, and `quantity: 0` removes it. The call emits the matching cart events as it starts, so they fire whether or not the change succeeds. The lines and note events carry a `context` of `standard-action` unless you set another. A rejected change resolves with `userErrors` rather than throwing, so check that array before reading `cart`. ## update​Cart(**[payload](#updatecart-propertydetail-payload)**​,**[options](#updatecart-propertydetail-options)**​) Adds, updates, or removes cart lines, sets the cart note, or applies discount codes. The call emits the matching cart events as it starts, so they fire whether or not the change succeeds. ### Parameters * **payload** **UpdateCartPayload** **required** * **options** **UpdateCartOptions** ### Returns * **Promise\** ### UpdateCartPayload The payload for an \`updateCart\` call. * cartId The cart to update. If omitted, the action finds the cart from the browser cookie or the AJAX API. ```ts string ``` * lines The lines to add, update, or remove. ```ts CartLineInput[] ``` * note A new cart note. ```ts string ``` * discountCodes The complete set of discount codes the cart should end up with. ```ts string[] ``` ### CartLineInput A cart line to add, update, or remove. * id The existing line ID, from either the Storefront API or the AJAX cart API. Include it to update or remove a line, and leave it out to add one. ```ts string ``` * merchandiseId The product variant GID, or a raw variant ID. Required when adding a line. ```ts string ``` * quantity The quantity for the line. Set it to \`0\` to remove the line. ```ts number ``` * attributes Custom key-value pairs to attach to the line. ```ts Array<{ key: string, value: string }> ``` * sellingPlanId The selling plan GID, or a raw selling plan ID, for a subscription or other selling plan. ```ts string ``` ### UpdateCartOptions Options for an \`updateCart\` call. * signal Aborts the request when the signal fires. ```ts AbortSignal ``` * event Shapes the events the call emits. ```ts UpdateCartEventOptions ``` ### UpdateCartEventOptions Shapes the events an \`updateCart\` call emits. * context Where the change came from. Sets the \`context\` field on the emitted \`shopify:cart:lines-update\` and \`shopify:cart:note-update\` events, and defaults to \`standard-action\`. ```ts 'product' | 'cart' | 'dialog' | 'standard-action' ``` * detail Custom data attached to the emitted events, which listeners read from the event. ```ts Record ``` ### UpdateCartResult The value an \`updateCart\` call resolves with. * cart The cart after the update, including \`lines\`, \`cost\`, and \`totalQuantity\`. ```ts CartSummary ``` * userErrors Present when the mutation was rejected. The cart stayed as it was for that input. Each entry has a \`message\`, and usually a code from \[\`CartErrorCode\`]\(/docs/api/storefront/latest/enums/CartErrorCode) and the \`field\` that caused it. ```ts CartMutationUserError[] ``` * warnings Present when the mutation succeeded but returned non-blocking warnings. The cart did change. Each entry has a \`message\`, and usually a code from \[\`CartWarningCode\`]\(/docs/api/storefront/latest/enums/CartWarningCode). ```ts CartMutationWarning[] ``` * detail Custom data attached by the storefront's handler, used to tell one update path from another. ```ts Record ``` ### CartSummary A cart, as actions report it. * id The cart GID. ```ts string ``` * totalQuantity The total number of items across every line. ```ts number ``` * cost The cart cost. ```ts CartCost ``` * lines The lines in the cart. ```ts CartLine[] ``` * discountCodes The discount codes on the cart. ```ts CartDiscountCode[] ``` ### CartCost The cost of a cart or a cart line. * totalAmount The total amount. ```ts Price ``` ### Price An amount with its currency. * amount A decimal money amount, such as \`29.99\`. ```ts string ``` * currencyCode The three-letter currency code, such as \`USD\`. ```ts string ``` ### CartLine A single line in the cart. * id The cart line ID. ```ts string ``` * quantity The quantity for the line. ```ts number ``` * cost The line cost. ```ts CartCost ``` ### CartDiscountCode A discount code on the cart. * applicable Whether the cart accepted the code. ```ts boolean ``` * code The code as the buyer entered it. ```ts string ``` ### 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 * #### Call the action ##### JavaScript ```javascript const { cart, userErrors, warnings } = await Shopify.actions.updateCart({ lines: [{ merchandiseId: 'gid://shopify/ProductVariant/123', quantity: 1 }], }); if (userErrors?.length) { showMessage(userErrors[0].message); return; } if (warnings?.length) { showMessage(warnings[0].message); } updateCartCount(cart.totalQuantity); ``` ##### Response ```json { "cart": { "id": "gid://shopify/Cart/c1-a1b2c3d4", "totalQuantity": 1, "cost": { "totalAmount": { "amount": "29.99", "currencyCode": "CAD" } }, "lines": [ { "id": "gid://shopify/CartLine/1", "quantity": 1, "cost": { "totalAmount": { "amount": "29.99", "currencyCode": "CAD" } } } ], "discountCodes": [] } } ``` * #### ##### Configure the action ```javascript Shopify.actions.updateCart.configure({ eventTarget: (meta) => { if (meta.type === 'shopify:cart:lines-update' && meta.action === 'add') { return document.querySelector('product-form'); } return document.querySelector('cart-drawer'); }, async handler(defaultHandler, payload, options) { const result = await defaultHandler(); await refreshCartSection(); return result; }, }); ``` ***