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

# Add Line Item

> Adds a product variant to the cart with automatic shipment grouping based on fulfillment requirements

## Overview

The Add Line Item endpoint adds a new product to the shopping cart with these features:

* **Automatic Shipment Assignment**: Items are automatically grouped into shipments based on their fulfillment requirements
* **Catalog Integration**: Uses `add_to_cart_ref` object directly from catalog API responses
* **Variant Support**: Handles configurable products with variant handles
* **Cart Creation**: Automatically creates a new cart if one doesn't exist
* **Optional Cart Clearing**: Can clear existing cart before adding new item

## Authentication

<Card>
  <ParamField header="x-firmly-authorization" type="string" required>
    Device authentication token to identify and map the session
  </ParamField>
</Card>

## Path Parameters

<ParamField path="domain" type="string" required>
  Domain of the merchant website (e.g., `staging.luma.gift`)
</ParamField>

## Query Parameters

<ParamField query="flush_cart" default="false" type="boolean">
  When `true`, clears the cart before adding the new item
</ParamField>

## Request Body

<ParamField body="add_to_cart_ref" type="object" required>
  Product reference from catalog API containing variant information

  **Properties:**

  * `variant_id` (string, required): Product variant identifier
  * `product_id` (string, optional): Parent product identifier
  * `variant_handles` (array, optional): Array of variant configuration handles (e.g., `["color:blue", "size:large"]`)
</ParamField>

<ParamField body="quantity" type="number" required>
  Quantity to add (minimum 1)
</ParamField>

## Response

Returns the complete shopping cart including the newly added item. See [Get Cart](/api-reference/cart-management/get-cart) for full response schema

### Key Response Features:

<ResponseField name="shipments" type="array">
  Shows automatic shipment assignment for the new item
</ResponseField>

<ResponseField name="addons.offers" type="array">
  Available addon services for the updated cart
</ResponseField>

<ResponseField name="schema_version" type="string">
  Indicates the cart schema version
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items \
    --header 'Content-Type: application/json' \
    --header 'x-firmly-authorization: YOUR_TOKEN' \
    --data '{
      "add_to_cart_ref": {
        "variant_id": "WS12-XS-Orange"
      },
      "quantity": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-firmly-authorization': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      add_to_cart_ref: {
        variant_id: 'WS12-XS-Orange'
      },
      quantity: 1
    })
  });

  const cart = await response.json();
  console.log(cart);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items',
      headers={
          'Content-Type': 'application/json',
          'x-firmly-authorization': 'YOUR_TOKEN'
      },
      json={
          'add_to_cart_ref': {
              'variant_id': 'WS12-XS-Orange'
          },
          'quantity': 1
      }
  )

  cart = response.json()
  print(cart)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  $data = [
      'add_to_cart_ref' => [
          'variant_id' => 'WS12-XS-Orange'
      ],
      'quantity' => 1
  ];

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Content-Type: application/json",
      "x-firmly-authorization: YOUR_TOKEN"
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  $cart = json_decode($response, true);
  print_r($cart);
  ?>
  ```
</CodeGroup>

## Advanced Examples

### With Variant Handles

For configurable products with multiple options:

```json theme={null}
{
  "add_to_cart_ref": {
    "variant_id": "MH07-XS-Gray",
    "variant_handles": ["color:gray", "size:xs"]
  },
  "quantity": 1
}
```

### Clear Cart First

To replace cart contents with a new item:

```bash theme={null}
curl --request POST \
  --url 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items?flush_cart=true' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{
    "add_to_cart_ref": {
      "variant_id": "WT09-XS-White"
    },
    "quantity": 2
  }'
```

## Catalog Integration

The `add_to_cart_ref` object should be passed directly from catalog API responses:

<CodeGroup>
  ```json Catalog API Response theme={null}
  {
    "products": [
      {
        "product_id": "WS12",
        "variants": [
          {
            "add_to_cart_ref": {
              "variant_id": "WS12-XS-Orange",
              "variant_handles": ["color:orange", "size:xs"]
            }
          }
        ]
      }
    ]
  }
  ```

  ```json Add to Cart Request theme={null}
  {
    "add_to_cart_ref": {
      "variant_id": "blue-sofa-large",
      "variant_handles": ["color:blue", "size:large"]
    },
    "quantity": 1
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "line_items": [
      {
        "line_item_id": "new-item-12345",
        "platform_line_item_id": "0",
        "sku": "WS12-XS-Orange",
        "variant_description": "Color: Orange, Size: XS",
        "description": "Radiant Tee",
        "base_sku": "WS12",
        "quantity": 1,
        "price": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "line_price": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "msrp": {
          "currency": "USD",
          "value": 22.00,
          "number": 2200,
          "symbol": "$"
        },
        "image": {
          "url": "https://cdn.staging.luma.gift/product/radiant-tee-orange.jpg",
          "alt": "Radiant Tee in Orange",
          "type": "default"
        },
        "requires_shipping": true
      }
    ],
    "shipments": [
      {
        "shipment_id": "auto-generated-shipment-1",
        "line_item_ids": ["new-item-12345"],
        "fulfillment_type": {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to your address"
        },
        "fulfillment_type_options": [
          {
            "id": "SHIP_TO_ADDRESS",
            "name": "Ship to Address", 
            "description": "Standard shipping to your address"
          },
          {
            "id": "SCHEDULED_DELIVERY",
            "name": "Scheduled Delivery",
            "description": "Delivery scheduled for a specific date"
          }
        ],
        "shipping_method_options": [
          {
            "id": "STANDARD_SHIPPING",
            "description": "Standard Shipping",
            "price": {
              "currency": "USD",
              "value": 50,
              "number": 5000,
              "symbol": "$"
            },
            "estimated_delivery": "5-7 business days"
          },
          {
            "id": "PREMIUM_SHIPPING",
            "description": "Premium Delivery",
            "price": {
              "currency": "USD",
              "value": 100,
              "number": 10000,
              "symbol": "$"
            },
            "estimated_delivery": "2-3 business days"
          }
        ],
        "shipping_method": {
          "id": "STANDARD_VENDOR_SHIPPING",
          "description": "Standard Shipping (O)",
          "price": {"value": 0, "currency": "USD", "number": 0, "symbol": "$"},
          "estimated_delivery": "Varies by vendor"
        },
        "notes": ""
      }
    ],
    "sub_total": {
      "currency": "USD",
      "value": 1299.99,
      "number": 129999,
      "symbol": "$"
    },
    "shipping_total": {
      "currency": "USD",
      "value": 0,
      "number": 0,
      "symbol": "$"
    },
    "tax_total": {
      "currency": "USD",
      "value": 0,
      "number": 0,
      "symbol": "$"
    },
    "total": {
      "currency": "USD",
      "value": 1299.99,
      "number": 129999,
      "symbol": "$"
    },
    "addons": {
      "offers": [
        {
          "addon_id": "protection-new-item-12345",
          "display": {
            "name": "Product Protection Plan"
          },
          "price": {
            "currency": "USD",
            "value": 0,
            "number": 0,
            "symbol": "$"
          },
          "scope": "ITEM",
          "coverage_mode": "PER_ITEM",
          "eligible_line_item_ids": [
            "new-item-12345"
          ],
          "child_offers": [
            {
              "addon_id": "A0-FURN-2y",
              "display": {
                "name": "2 Year Protection"
              },
              "scope": "INHERIT",
              "coverage_mode": "PER_ITEM",
              "eligible_line_item_ids": [
                "new-item-12345"
              ],
              "price": {
                "currency": "USD",
                "value": 149.99,
                "number": 14999,
                "symbol": "$"
              }
            },
            {
              "addon_id": "A0-FURN-3y",
              "display": {
                "name": "3 Year Protection"
              },
              "scope": "INHERIT",
              "coverage_mode": "PER_ITEM",
              "eligible_line_item_ids": [
                "new-item-12345"
              ],
              "price": {
                "currency": "USD",
                "value": 199.99,
                "number": 19999,
                "symbol": "$"
              }
            }
          ]
        }
      ],
      "selections": []
    },
    "addon_total": {
      "currency": "USD",
      "value": 0,
      "number": 0,
      "symbol": "$"
    },
    "schema_version": "2.0"
  }
  ```
</ResponseExample>

## Error Responses

<Accordion title="400 Bad Request">
  Invalid request format or missing required parameters

  ```json theme={null}
  {
    "code": 400,
    "error": "ErrorInvalidInputBody",
    "description": "Request body validation failed"
  }
  ```
</Accordion>

<Accordion title="404 Not Found">
  Product variant not found in catalog

  ```json theme={null}
  {
    "code": 404,
    "error": "ErrorProductNotFound",
    "description": "Product variant was not found"
  }
  ```
</Accordion>

<Accordion title="409 Conflict">
  Product is not supported for cart operations

  ```json theme={null}
  {
    "code": 400,
    "error": "ErrorProductNotSupported",
    "description": "Product is not supported for this operation"
  }
  ```
</Accordion>

<Accordion title="422 Unprocessable Entity">
  Various processing errors

  ```json theme={null}
  {
    "code": 400,
    "error": "ErrorNotEnoughStock",
    "description": "Insufficient stock for requested quantity"
  }
  ```
</Accordion>

## Automatic Shipment Assignment

<Note>
  When adding items to the cart, the system automatically:

  1. **Groups compatible items**: Items with similar fulfillment requirements are grouped together
  2. **Creates new shipments**: Items with different requirements get separate shipments
  3. **Inherits options**: New shipments inherit available fulfillment and shipping options
</Note>

### Example: Mixed Cart

Adding a large sofa (requires scheduled delivery) to a cart with small accessories (standard shipping) creates separate shipments:

```json theme={null}
{
  "shipments": [
    {
      "shipment_id": "furniture-shipment",
      "line_item_ids": ["hoodie-item"],
      "fulfillment_type": {"id": "SCHEDULED_DELIVERY"}
    },
    {
      "shipment_id": "accessories-shipment", 
      "line_item_ids": ["tee-item", "tank-item"],
      "fulfillment_type": {"id": "SHIP_TO_ADDRESS"}
    }
  ]
}
```

## Related Endpoints

* [Get Cart](/api-reference/cart-management/get-cart) - View current cart state
* [Update Line Item](/api-reference/cart-management/update-line-item) - Modify cart items
* [Clear Cart](/api-reference/cart-management/clear-cart) - Empty the cart