> ## 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 Item to Cart

> Adds a product to the shopping cart

## Overview

Adds a product to the cart using its SKU. To find available products and their SKUs, use the [Catalog API](/api-reference/catalog/overview).

## Authentication

<Card>
  <ParamField header="x-firmly-authorization" type="string" required>
    Device authentication token from browser session
  </ParamField>
</Card>

## Path Parameters

<ParamField path="domain" type="string" required>
  Merchant domain (e.g., `staging.luma.gift`)
</ParamField>

<ParamField path="sku" type="string" required>
  Product SKU to add to cart (e.g., `WS12-XS-Orange`)
</ParamField>

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

## Request Body

<ParamField body="variant_handles" type="array">
  List of variant handles required by some merchants to fully identify the product
</ParamField>

## Query Parameters

<ParamField query="flush_cart" default="false" type="string">
  Set to `true` to clear the cart before adding the item
</ParamField>

<ParamField query="fast_mode" default="false" type="string">
  Set to `true` for faster response with potentially cached data
</ParamField>

## Response

Returns the updated shopping cart.

### Response Fields

<ResponseField name="cart_id" type="string">
  Unique identifier for the cart
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of items in the cart

  <Expandable title="Line Item Object">
    <ResponseField name="line_item_id" type="string">
      Unique identifier for the line item
    </ResponseField>

    <ResponseField name="sku" type="string">
      Product SKU
    </ResponseField>

    <ResponseField name="base_sku" type="string">
      Base product SKU (parent product)
    </ResponseField>

    <ResponseField name="quantity" type="number">
      Quantity of the item
    </ResponseField>

    <ResponseField name="description" type="string">
      Product description
    </ResponseField>

    <ResponseField name="price" type="object">
      Unit price
    </ResponseField>

    <ResponseField name="line_price" type="object">
      Total price for this line item (price × quantity)
    </ResponseField>

    <ResponseField name="image" type="object">
      Product image
    </ResponseField>

    <ResponseField name="requires_shipping" type="boolean">
      Whether this item requires shipping
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sub_total" type="object">
  Subtotal before shipping and tax
</ResponseField>

<ResponseField name="shipping_total" type="object">
  Shipping cost (if shipping info has been set)
</ResponseField>

<ResponseField name="tax" type="object">
  Tax amount
</ResponseField>

<ResponseField name="total" type="object">
  Grand total including all costs
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1 \
    --header 'x-firmly-authorization: YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.firmly.work/api/v1/domains/staging.luma.gift/cart/line-items/WS12-XS-Orange/quantity/1', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': 'YOUR_TOKEN'
    }
  });

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

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

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

  cart = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "cart_id": "1e43868c-d4a5-418c-bd6b-5fff043550d2",
    "platform_id": "example",
    "shop_id": "staging.luma.gift",
    "display_name": "Luma Store",
    "line_items": [
      {
        "line_item_id": "1ee530e1-063d-4e07-afb2-e7e65245977e",
        "platform_line_item_id": "4df9941b-bd06-4495-8759-61c6145dc408",
        "sku": "WS12-XS-Orange",
        "base_sku": "WS12",
        "quantity": 1,
        "description": "Radiant Tee - Orange XS",
        "price": {
          "currency": "USD",
          "value": 22.00,
          "symbol": "$",
          "number": 2200
        },
        "line_price": {
          "currency": "USD",
          "value": 22.00,
          "symbol": "$",
          "number": 2200
        },
        "msrp": {
          "currency": "USD",
          "value": 22.00,
          "symbol": "$",
          "number": 2200
        },
        "image": {
          "url": "https://cdn.staging.luma.gift/products/radiant-tee/orange.jpg"
        },
        "requires_shipping": true
      }
    ],
    "sub_total": {
      "currency": "USD",
      "value": 869.99,
      "symbol": "$",
      "number": 86999
    },
    "shipping_total": {
      "currency": "USD",
      "value": 0,
      "symbol": "$",
      "number": 0
    },
    "tax": {
      "currency": "USD",
      "value": 2.20,
      "symbol": "$",
      "number": 220
    },
    "total": {
      "currency": "USD",
      "value": 24.20,
      "symbol": "$",
      "number": 2420
    },
    "payment_method_options": [
      {
        "type": "CreditCard",
        "wallet": "user"
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

### 400 Bad Request

Missing or invalid authentication header

### 404 Not Found

Product not found with the given SKU

### 409 Conflict

Not enough stock available for the requested quantity

### 422 Unprocessable Entity

Invalid request body format