Add to Cart

Add product variants to a shopping cart

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

cartId · string · required

The ID of the cart to add items to

data · CartUpdateInput · required

The cart update data

Show CartUpdateInput

lineItems · LineItemRelateInput · required

Line items to add to the cart

Show LineItemRelateInput

create · array

Array of line items to create

Show LineItemCreateInput[]

productVariant · object · required

connect · object · required

id · string · required

The ID of the product variant to add

quantity · integer · required

Quantity of this variant to add (must be positive)

metadata · object

Optional metadata for the line item (e.g., customization options)

Response

id · string

Cart identifier

lineItems · array

Updated array of line items in the cart

Show LineItem[]

id · string

Line item identifier

quantity · integer

Quantity of this item

title · string

Product variant title

unitPrice · string

Formatted unit price (e.g., “$29.99”)

total · string

Formatted total price for this line item (unitPrice × quantity)

productVariant · object

Product variant details

Show ProductVariant

id · string

Variant identifier

title · string

Variant title (e.g., “Black / Large”)

sku · string

Stock keeping unit code

product · object

id · string

Product identifier

title · string

Product title

thumbnail · string

Product thumbnail image URL

subtotal · string

Formatted cart subtotal (sum of all line items before tax and shipping)

total · string

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
          }
        ]
      }
    }
  }
);

Add Item with Metadata

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:

1. The system finds the price for the product variant in the cart’s region
2. Applies any active discounts that match discount conditions
3. Calculates line item totals
4. 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:

1. Set or update shipping/billing addresses
2. Apply discount codes (optional)
3. Select shipping method
4. Create payment sessions
5. Complete the cart to create an order

Related

• Create Cart - Initialize a new cart
• Complete Cart - Convert cart to order
• Update Line Item Quantity - Modify existing line items
• Remove Line Item - Remove items from cart