Add to Cart

About

The addProductToCart mutation adds a product to a customer's shopping cart. Use this mutation to:

• Add products from product detail pages to cart
• Implement "Add to Cart" buttons and flows
• Add products programmatically from search results
• Handle quantity selection and variant options
• Update cart inventory reservations
• Track product additions for analytics

This mutation validates product availability, applies applicable pricing rules, and updates the cart total. It handles both simple products and configurable products with variants.

Authentication

This mutation supports both authenticated customers and guest users:

• Authenticated customers: Provide a valid customer authentication token in the Authorization header. Obtain this token via the Customer Login API.
• Guest users: Provide the Guest Cart Token cartToken obtained from the Create Cart mutation.

Authorization: Bearer <accessToken>

Arguments

Argument	Type	Description
cart_id	String!	Cart token from createCart mutation. Identifies which cart to add to.
product_id	ID!	The product to add. Use product ID from product queries.
quantity	Int!	Number of units to add (must be >= 1).
variant_id	ID	For configurable products, the specific variant to add.
options	[CartItemOption!]	Product-specific options (colors, sizes, custom text).
custom_attributes	[CustomAttribute!]	Custom product attributes and their selected values.

Possible Returns

Field	Type	Description
cart	Cart!	Updated cart with the new item added.
cartItem	CartItem!	The newly added cart line item.
cartItem.id	String!	Unique cart item identifier.
cartItem.product	Product!	Product information.
cartItem.quantity	Int!	Quantity added.
cartItem.price	Float!	Unit price at time of addition.
cartItem.lineTotal	Float!	Total for this line item.
message	String!	Success message or error description.
success	Boolean!	Indicates successful addition.
errors	[ErrorMessage!]	Validation errors (insufficient stock, invalid options, etc.).