---
title: Cart warnings
description: Learn about cart warnings and how they can help you manage your cart.
source_url:
  html: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/cart-warnings
  md: >-
    https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/cart-warnings.md
api_name: storefront
---

# Cart warnings

Cart warnings inform clients about automatic changes that a GraphQL mutation has made to a cart. Unlike a user error, which indicates a mutation failure, a warning confirms the mutation's success and the automatic changes it has made to the cart. All successful cart mutations can generate an array of [`CartWarning` objects](https://shopify.dev/docs/api/storefront/2024-10/objects/CartWarning). Each warning contains a discrete code, localized message and the ID of the targeted object in the cart. Clients can choose to address an automatic change, but action isn't required.

For example, if an item that was previously added to the cart becomes out of stock during the addition of another product, we'll issue a warning indicating `MERCHANDISE_OUT_OF_STOCK` with the ID of the cart line for that out of stock item.

An example call to [`cartLinesAdd`](https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesAdd) is shown below.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation CartLinesAdd{
  cartLinesAdd(
    cartId: "gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK?key=766f90254525fd796c615126ff31ccab",
    lines: [
      {
        merchandiseId: "gid://shopify/ProductVariant/2",
        quantity: 2
      }
    ]
  ) {
    cart {
      id
      lines(first: 5) {
        edges {
          node {
            id
            merchandise {
              ...  on ProductVariant {
                id
                quantity
              }
            }
          }
        }
      }
    }
    warnings {
      code
      target
      message
    }
    userErrors {
      code
      message
      field
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "cartLinesAdd": {
      "cart": {
        "id": "gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK?key=766f90254525fd796c615126ff31ccab",
        "lines": {
          "edges": [
            {
              "node": {
                "id": "gid://shopify/CartLine/8ecc247c-0578-490d-b522-a12412dfc628?cart=Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK",
                "merchandise": {
                  "id": "gid://shopify/ProductVariant/2",
                  "quantity": "2"
                }
              }
            },
            {
              "node": {
                "id": "gid://shopify/CartLine/1a44a5cb-82dc-4eae-a99e-548b6f9146c2?cart=Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK",
                "merchandise": {
                  "id": "gid://shopify/ProductVariant/3",
                  "quantity": "0"
                }
              }
            }
          ]
        }
      },
      "warnings": [
        {
          "code": "MERCHANDISE_OUT_OF_STOCK",
          "target": "gid://shopify/CartLine/1a44a5cb-82dc-4eae-a99e-548b6f9146c2?cart=Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK",
          "message": "The product 'Merchandise Title' is already sold out."
        }
      ],
      "userErrors": []
    }
  }
}
```

Clients can take the [`target`](https://shopify.dev/docs/api/storefront/2024-10/objects/CartWarning#field-target) from a warning and construct a call to [`CartLinesRemove`](https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesRemove) to remove an out of stock item.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation CartLinesRemove{
  cartLinesRemove(
    cartId: "gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK?key=766f90254525fd796c615126ff31ccab",
    lineIds: [
      "gid://shopify/CartLine/1a44a5cb-82dc-4eae-a99e-548b6f9146c2?cart=Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK"
    ]
  ) {
    cart {
      id
      lines(first: 5) {
        edges {
          node {
            id
            merchandise {
              ...  on ProductVariant {
                id
                quantity
              }
            }
          }
        }
      }
    }
    warnings {
      code
      target
      message
    }
    userErrors {
      code
      message
      field
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "cartLinesRemove": {
      "cart": {
        "id": "gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK?key=766f90254525fd796c615126ff31ccab",
        "lines": {
          "edges": [
            {
              "node": {
                "id": "gid://shopify/CartLine/8ecc247c-0578-490d-b522-a12412dfc628?cart=Z2NwLXVzLWVhc3QxOjAxSjZGSFIwMjU1WUZITVRBOUpRQTQ3VjRK",
                "merchandise": {
                  "id": "gid://shopify/ProductVariant/2",
                  "quantity": 2
                }
              }
            }
          ]
        }
      },
      "warnings": [],
      "userErrors": []
    }
  }
}
```

***