updateCart

Adds, updates, or removes cart lines, sets the cart note, applies discount codes, and updates cart attributes. 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 this action refreshes its own UI. Without a configuration, the default refreshes the cart on themes it recognizes, 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.

attributes is the complete set of cart attributes the cart should end up with, replacing the existing set rather than merging with it. Leaving out an existing key removes it, and an empty array clears all attributes. The resolved cart doesn't include attributes, so read the set you submitted or fetch it separately.

The call emits the matching cart events as it starts, so they fire whether or not the change succeeds. The lines, note, and attributes 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.

Anchor to updateCart
updateCart(
payload
,
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.

Anchor to updateCart-parametersParameters

Anchor to payload payload required
Anchor to options options

Anchor to updateCart-returnsReturns

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.
```
string
```
lines
The lines to add, update, or remove.
```
CartLineInput[]
```
note
A new cart note.
```
string
```
discountCodes
The complete set of discount codes the cart should end up with.
```
string[]
```
attributes
The complete set of cart attributes the cart should end up with, replacing the existing set. The Storefront API accepts at most 250 values.
```
CartAttributeInput[]
```

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.
```
string
```
merchandiseId
The product variant GID, or a raw variant ID. Required when adding a line.
```
string
```
quantity
The quantity for the line. Set it to `0` to remove the line.
```
number
```
attributes
Custom key-value pairs to attach to the line.
```
CartAttributeInput[]
```
sellingPlanId
The selling plan GID, or a raw selling plan ID, for a subscription or other selling plan.
```
string
```

CartAttributeInput

A custom key-value pair for a cart or cart line.

key
The attribute's key.
```
string
```
value
The attribute's value.
```
string
```

UpdateCartOptions

Options for an `updateCart` call.

signal
Aborts the request when the signal fires.
```
AbortSignal
```
event
Shapes the events the call emits.
```
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`.
```
'product' | 'cart' | 'dialog' | 'standard-action'
```
detail
Custom data attached to the emitted events, which listeners read from the event.
```
Record<string, unknown>
```

UpdateCartResult

The value an `updateCart` call resolves with.

cart
The cart after the update, including `lines`, `cost`, and `totalQuantity`.
```
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.
```
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).
```
CartMutationWarning[]
```
detail
Custom data attached by the storefront's handler, used to tell one update path from another.
```
Record<string, unknown>
```

CartSummary

A cart, as actions report it.

id
The cart GID.
```
string
```
totalQuantity
The total number of items across every line.
```
number
```
cost
The cart cost.
```
CartCost
```
lines
The lines in the cart.
```
CartLine[]
```
discountCodes
The discount codes on the cart.
```
CartDiscountCode[]
```

CartCost

The cost of a cart or a cart line.

totalAmount
The total amount.
```
Price
```

Price

An amount with its currency.

amount
A decimal money amount, such as `29.99`.
```
string
```
currencyCode
The three-letter currency code, such as `USD`.
```
string
```

CartLine

A single line in the cart.

id
The cart line ID.
```
string
```
quantity
The quantity for the line.
```
number
```
cost
The line cost.
```
CartCost
```

CartDiscountCode

A discount code on the cart.

applicable
Whether the cart accepted the code.
```
boolean
```
code
The code as the buyer entered it.
```
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.
```
string
```
field
The path to the field that caused the error.
```
string[]
```
message
A human-readable message.
```
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.
```
string
```
message
A human-readable message.
```
string
```
target
The cart line or field the warning applies to.
```
string
```

Examples

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);

Examples

Call the action

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

{
  "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

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;
  },
});

Was this page helpful?

Anchor to updateCartupdateCart(payloadpayload,optionsoptions)

Anchor to updateCart-parametersParameters

Anchor to updateCart-returnsReturns

UpdateCartPayload

CartLineInput

CartAttributeInput

UpdateCartOptions

UpdateCartEventOptions

UpdateCartResult

CartSummary

CartCost

Price

CartLine

CartDiscountCode

CartMutationUserError

CartMutationWarning

Examples

Call the action

JavaScript

Response

Configure the action

Anchor to updateCart
updateCart(
payload
,
options
)