> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Item to Cart

> Add a product to an existing cart

<Note>
  This endpoint adds one or more items to a cart. If the item already exists, it updates the quantity. Inventory availability is checked in real-time.
</Note>

## Authentication

This endpoint requires a valid API key with `carts:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the cart
</ParamField>

## Request Body

<ParamField body="product_id" type="string" required>
  Product ID to add
</ParamField>

<ParamField body="variant_id" type="string">
  Product variant ID (required if product has variants)
</ParamField>

<ParamField body="quantity" type="integer" required>
  Quantity to add (must be positive)
</ParamField>

<ParamField body="price_override" type="integer">
  Custom price in cents (requires special permissions)
</ParamField>

<ParamField body="notes" type="string">
  Special instructions for this item
</ParamField>

<ParamField body="metadata" type="object">
  Custom fields for the item
</ParamField>

<ParamField body="validate_inventory" type="boolean" default="true">
  Check inventory availability before adding
</ParamField>

<ParamField body="replace_quantity" type="boolean" default="false">
  Replace existing quantity instead of adding to it
</ParamField>

### Response

Returns the updated cart object.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/carts/cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/items' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "product_id": "prod_789",
      "variant_id": "var_red_medium",
      "quantity": 1,
      "notes": "Gift wrap please"
  }'
  ```

  ```javascript Node.js theme={null}
  const cart = await stateset.carts.addItem(
    'cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    {
      product_id: "prod_789",
      variant_id: "var_red_medium",
      quantity: 1,
      notes: "Gift wrap please"
    }
  );
  ```

  ```python Python theme={null}
  cart = stateset.carts.add_item(
    'cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    product_id="prod_789",
    variant_id="var_red_medium",
    quantity=1,
    notes="Gift wrap please"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "cart",
    "customer_id": "cust_abc123",
    "status": "active",
    "items": [
      {
        "id": "ci_abc123",
        "product_id": "prod_123",
        "variant_id": "var_blue_large",
        "product_name": "Wireless Headphones",
        "variant_name": "Blue - Large",
        "quantity": 2,
        "unit_price": 9999,
        "subtotal": 19998
      },
      {
        "id": "ci_def456",
        "product_id": "prod_456",
        "product_name": "USB-C Cable",
        "quantity": 1,
        "unit_price": 1999,
        "subtotal": 1999
      },
      {
        "id": "ci_ghi789",
        "product_id": "prod_789",
        "variant_id": "var_red_medium",
        "product_name": "T-Shirt",
        "variant_name": "Red - Medium",
        "quantity": 1,
        "unit_price": 2499,
        "subtotal": 2499,
        "notes": "Gift wrap please",
        "inventory_status": "in_stock",
        "available_quantity": 15
      }
    ],
    "item_count": 4,
    "unique_item_count": 3,
    "subtotal": 24496,
    "tax_amount": 0,
    "shipping_amount": 0,
    "discount_amount": 2000,
    "total": 22496,
    "updated_at": "2024-06-20T15:00:00Z",
    "last_activity": "2024-06-20T15:00:00Z",
    "messages": [
      {
        "type": "info",
        "message": "Item added successfully"
      }
    ]
  }
  ```
</ResponseExample>