cartLineItemsAdd

Mutationin Cart

Add line items to cart or create a new cart

Arguments

Argument	Type	Description
`id`	`ID`
`version`	`String`
`lineItems`	`[CartLineItemAddInput!]!`

Returns

CartLineItemsAddResponse!

Field	Type	Description
`cart`	`Cart`	Cart information after line items are added
`lineResults`	`[CartLineItemAddResult!]`	One result per requested line, in the order requested: added, or why not. Lines that can be added are added even when others cannot. Null when the request failed as a whole, which cartErrors then says.
`addedQuantity`	`Int`	How many items were added in total, counted by quantity.
`addedAmount`	`Money`	What the added lines add to the cart total. Null when the request failed as a whole.
`cartErrors`	`[CartLineItemsAddError!]`	Error details if line item addition failed

Example

mutation CartLineItemsAdd(
  $id: ID
  $version: String
  $lineItems: [CartLineItemAddInput!]!
) {
  cartLineItemsAdd(id: $id, version: $version, lineItems: $lineItems) {
    cart {
      id
      version
      createdAt
      lastModifiedAt
      currency
      customerEmail
      isGuest
      totalQuantity
      deliveryRemarks
      vatNumber
      purchaseOrderNumber
      deliverySplit
      requestedDeliveryDate
      earliestCompleteDeliveryDate
      name
      defaultName
      status
    }
    lineResults {
      sku
      quantity
      failure
      message
    }
    addedQuantity
    addedAmount {
      centAmount
      currency
    }
    cartErrors {
      __typename
      ... on ValidationError {
        message
      }
      ... on CartError {
        message
        code
      }
    }
  }
}

{
  "id": "id-1",
  "version": "Example",
  "lineItems": [
    {
      "sku": "SKU-1",
      "quantity": 1,
      "addOns": [
        {
          "sku": "SKU-1",
          "quantity": 1
        }
      ]
    }
  ]
}

{
  "data": {
    "cartLineItemsAdd": {
      "cart": {
        "id": "id-1",
        "version": "Example",
        "createdAt": "2026-10-01T09:30:00Z",
        "lastModifiedAt": "2026-10-01T09:30:00Z",
        "currency": "EUR",
        "customerEmail": "jane@example.com",
        "isGuest": true,
        "totalQuantity": 1,
        "deliveryRemarks": "Example",
        "vatNumber": "Example",
        "purchaseOrderNumber": "Example",
        "deliverySplit": "COMPLETE",
        "requestedDeliveryDate": "2026-10-01",
        "earliestCompleteDeliveryDate": "2026-10-01",
        "name": "Example",
        "defaultName": "Example",
        "status": "ACTIVE"
      },
      "lineResults": [
        {
          "sku": "SKU-1",
          "quantity": 1,
          "failure": "NOT_FOUND",
          "message": "Example"
        }
      ],
      "addedQuantity": 1,
      "addedAmount": {
        "centAmount": 1,
        "currency": "EUR"
      },
      "cartErrors": [
        {
          "__typename": "ValidationError",
          "message": "Example"
        }
      ]
    }
  }
}

The query selects the return type's fields two levels deep; pick the ones you need. The response shows its shape with placeholder values.

Served by

@evolve-framework/commercetools	Resolved
@evolve-framework/medusa	Resolved
@evolve-framework/sfcc	Resolved

Used by

The storefront packages that send it, in these GraphQL documents:

@evolve-storefront/feature-cart: CartLineItemsAdd