Overview The updateActiveCart mutation with line items allows you to add product variants to an existing cart. This is the second step in the checkout flow after creating a cart.
GraphQL Mutation mutation UpdateActiveCart ( $cartId : ID ! , $data : CartUpdateInput ! ) { updateActiveCart ( cartId : $cartId , data : $data ) { id lineItems { id quantity title unitPrice total productVariant { id title sku product { id title thumbnail } } } subtotal total } }
Parameters The ID of the cart to add items to
The cart update data lineItems
LineItemRelateInput
required
Line items to add to the cart Array of line items to create Show LineItemCreateInput[]
The ID of the product variant to add
Quantity of this variant to add (must be positive)
Optional metadata for the line item (e.g., customization options)
Response Updated array of line items in the cart Formatted unit price (e.g., “$29.99”)
Formatted total price for this line item (unitPrice × quantity)
Product variant details Variant title (e.g., “Black / Large”)
Product thumbnail image URL
Formatted cart subtotal (sum of all line items before tax and shipping)
Formatted cart total (subtotal + shipping + tax - discounts)
Example Request Add Single Item const { updateActiveCart } = await openfrontClient . request ( gql ` mutation UpdateActiveCart($cartId: ID!, $data: CartUpdateInput!) { updateActiveCart(cartId: $cartId, data: $data) { id lineItems { id quantity title unitPrice } subtotal total } } ` , { cartId: "clx123abc456" , data: { lineItems: { create: [ { productVariant: { connect: { id: "clx789xyz012" } }, quantity: 1 } ] } } } );
Add Multiple Items const { updateActiveCart } = await openfrontClient . request ( gql ` mutation UpdateActiveCart($cartId: ID!, $data: CartUpdateInput!) { updateActiveCart(cartId: $cartId, data: $data) { id lineItems { id quantity } } } ` , { cartId: "clx123abc456" , data: { lineItems: { create: [ { productVariant: { connect: { id: "clx789xyz012" } }, quantity: 2 }, { productVariant: { connect: { id: "clx789xyz013" } }, quantity: 1 } ] } } } );
const { updateActiveCart } = await openfrontClient . request ( gql ` mutation UpdateActiveCart($cartId: ID!, $data: CartUpdateInput!) { updateActiveCart(cartId: $cartId, data: $data) { id lineItems { id metadata } } } ` , { cartId: "clx123abc456" , data: { lineItems: { create: [ { productVariant: { connect: { id: "clx789xyz012" } }, quantity: 1 , metadata: { engraving: "John Doe" , giftWrap: true } } ] } } } );
Behavior Price Calculation When items are added to the cart:
The system finds the price for the product variant in the cart’s region
Applies any active discounts that match discount conditions
Calculates line item totals
Updates cart subtotal and total with tax and shipping
Inventory Validation The system validates:
Product variant exists and is active
Sufficient inventory is available (if inventory tracking is enabled)
Variant is available in the cart’s region
Duplicate Items If you add a product variant that already exists in the cart, a new line item is created. To increase quantity of an existing item, use the update operation instead:
data : { lineItems : { update : [ { where: { id: "existingLineItemId" }, data: { quantity: 3 } } ] } }
Automatic Calculations Adding items triggers automatic recalculation of:
Line item totals
Cart subtotal
Discount amounts (if applicable)
Tax amount based on region tax rate
Cart total
Next Steps After adding items to the cart:
Set or update shipping/billing addresses
Apply discount codes (optional)
Select shipping method
Create payment sessions
Complete the cart to create an order