AddProductsToCartMutation

Description

Adds one or more products to a cart. Pass the cartId and an array of AddCartItemInput objects — each specifying a SKU, an optional quantity, and optional custom data (matrix variant selection, gift card value, etc.).

If a product matching the given SKU is already in the cart, its quantity is incremented rather than a duplicate line being created.

tip

You can add multiple products in a single call by providing more than one entry in the items array. The mutation returns the full updated cart, so there is no need to follow up with a cart query.

Endpoint

mutation addProductsToCart($cartId: String!, $items: [AddCartItemInput!]) {
  addProductsToCart(cartId: $cartId, items: $items) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart to which products will be added. This ID is obtained from createGuestCart or createCustomerCart mutations.
siteId	Int	No	The site ID where the cart is created. Defaults to 1 if not provided.
items	[AddCartItemInput]	No	A list of items to add to the cart.

AddCartItemInput

Field	Type	Required	Description
sku	String	Yes	The SKU or handle of the product to add to the cart.
qty	Int	No	The quantity of the product to add. Defaults to 1 if not provided.
custom	Object	No	Custom data for the cart item.

Custom Data Fields

The custom object can contain the following special fields:

Field	Type	Description
_attributeY	String	Y-axis attribute for product matrix selection.
_attributeX	String	X-axis attribute for product matrix selection.
_giftCardValue	Float	Custom value for gift cards.

Additional custom fields can be included as needed and will be stored with the cart item.

Return Values

The mutation returns a CartType object with the following structure:

Field	Type	Description
billing_address	Object	The billing address associated with the cart.
shipping_address	Object	The shipping address associated with the cart.
items	[CartItem]	Array of items in the cart.
selected_shipping_method	Object	The selected shipping method for the cart.
selected_payment_method	Object	The selected payment method for the cart.
totals	Object	Cart totals information.

CartItem Structure

Each item in the items array contains:

Field	Type	Description
id	String	Unique identifier for the cart item.
quantity	Int	Quantity of the product in the cart.
tax_percent	Float	Tax percentage applied to this item.
total_weight	Float	Total weight of this item.
name	String	Product name.
sku	String	Product SKU.
thumbnail	String	URL to the product thumbnail image.
custom	Object	Custom data associated with this item.
price	Money	Base price of the product.
price_tax_amount	Money	Tax amount for a single unit.
price_including_tax	Money	Price including tax for a single unit.
price_excluding_tax	Money	Price excluding tax for a single unit.
row_total	Money	Total price for this item (quantity × price).
row_total_tax_amount	Money	Total tax amount for this item.
row_total_including_tax	Money	Total price including tax for this item.
row_total_excluding_tax	Money	Total price excluding tax for this item.

Money Structure

Price fields use the Money structure:

Field	Type	Description
value	Float	The numerical value.
currency	String	The currency code (e.g., "USD").

Usage Example

mutation {
  addProductsToCart(
    cartId: "abc123",
    items: [
      {
        sku: "product-123",
        qty: 2,
        custom: {
          _attributeY: "color",
          _attributeX: "red"
        }
      }
    ]
  ) {
    items {
      id
      quantity
      name
      sku
      price {
        value
        currency
      }
      row_total {
        value
        currency
      }
    }
    totals {
      grand_total {
        value
        currency
      }
    }
  }
}

Example Response

{
  "data": {
    "addProductsToCart": {
      "items": [
        {
          "id": "123",
          "quantity": 2,
          "name": "Sample Product",
          "sku": "product-123",
          "price": {
            "value": 19.99,
            "currency": "USD"
          },
          "row_total": {
            "value": 39.98,
            "currency": "USD"
          }
        }
      ],
      "totals": {
        "grand_total": {
          "value": 39.98,
          "currency": "USD"
        }
      }
    }
  }
}

Notes

• Products are identified by their SKU/handle, not by their numeric ID.
• If the product is already in the cart the specified quantity is added to the existing line — a duplicate item is not created.
• Stock validation runs when catalog stock management is enabled. An error is returned if the requested quantity exceeds available stock.
• If guest checkout is disabled and no authenticated customer is present, the mutation returns an error.
• _attributeY / _attributeX in custom are for matrix-variation products. Pass the axis labels (e.g. "color" / "red"), not the display names.
• _giftCardValue is only valid for gift card product types and is ignored otherwise.

warning

Always obtain a valid cartId via createGuestCart or createCustomerCart before calling this mutation. Passing an unknown or expired cart ID returns an error.