AddProductsToCartMutation

Description

Adds one or more products to the cart. This mutation allows you to specify product SKUs, quantities, and custom attributes for each item being added.

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 ID.
• If the product is already in the cart, this mutation will add the specified quantity to the existing quantity.
• Stock validation is performed if catalog stock management is enabled. An error will be thrown if the requested quantity exceeds available stock.
• Guest checkout validation is performed. An error will be thrown if guest checkout is disabled and the user is not logged in.
• The attribute matrix (attributeX and attributeY) is used for products with matrix-based variations.
• Custom gift card values are only applicable for gift card products.