> ## 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.

# Update Line Item

> Updates the quantity of an existing line item in the shopping cart

## Overview

The Update Line Item endpoint modifies the quantity of an existing product in the cart. Key features include:

* **Quantity Modification**: Update item quantities or remove items by setting quantity to 0
* **Automatic Recalculation**: All pricing and shipment information is automatically updated
* **Shipment Preservation**: Items remain in their assigned shipments after quantity updates
* **Addon Adjustment**: Addon offers may change based on new cart totals

## 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>

<ParamField path="lineItemId" type="string" required>
  Unique identifier of the line item to update
</ParamField>

## Request Body

<ParamField body="quantity" type="number" required>
  New quantity for the line item (minimum 0, set to 0 to remove the item)
</ParamField>

## Response

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

### Update Behavior:

* **Quantity > 0**: Updates the item quantity and recalculates pricing
* **Quantity = 0**: Removes the item from the cart and its shipment
* **Empty Shipments**: Shipments with no remaining items are automatically removed

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items/item_01H2XVBR8C8JS5MQSFPJ8HF9SB \
    --header 'Content-Type: application/json' \
    --header 'x-firmly-authorization: YOUR_TOKEN' \
    --data '{
      "quantity": 2
    }'
  ```

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

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

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

  response = requests.put(
      'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items/item_01H2XVBR8C8JS5MQSFPJ8HF9SB',
      headers={
          'Content-Type': 'application/json',
          'x-firmly-authorization': 'YOUR_TOKEN'
      },
      json={
          'quantity': 2
      }
  )

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

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

  $data = [
      'quantity' => 2
  ];

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/line-items/item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    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>

## Example Scenarios

### Increase Quantity

Update an item from quantity 1 to 2:

```json theme={null}
// Request
{
  "quantity": 2
}

// Response shows updated quantity and recalculated totals
{
  "line_items": [
    {
      "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "quantity": 2,
      "price": {
        "value": 54.00
      },
      "line_price": {
        "value": 108.00
      }
    }
  ],
  "sub_total": {
    "value": 108.00
  }
}
```

### Remove Item

Set quantity to 0 to remove an item:

```json theme={null}
// Request
{
  "quantity": 0
}

// Response shows item removed from cart and shipments
{
  "line_items": [],
  "shipments": [],
  "sub_total": {
    "value": 0
  }
}
```

<ResponseExample>
  ```json theme={null}
  {
    "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
    "platform_id": "shopify",
    "shop_id": "staging.luma.gift",
    "display_name": "Luma Store",
    "cart_status": "active",
    "line_items": [
      {
        "line_item_id": "item_01H2XVBR8C8JS5MQSFPJ8HF9SB",
        "sku": "MH07-XS-Gray",
        "variant_id": "MH07-XS-Gray",
        "description": "Hero Hoodie - Gray XS",
        "quantity": 2,
        "price": {
          "currency": "USD",
          "value": 54.00,
          "number": 5400,
          "symbol": "$"
        },
        "line_price": {
          "currency": "USD",
          "value": 108.00,
          "number": 10800,
          "symbol": "$"
        }
      }
    ],
    "shipments": [
      {
        "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SC",
        "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
        "fulfillment_type": {
          "id": "SHIP_TO_ADDRESS",
          "name": "Ship to Address",
          "description": "Standard shipping to customer address"
        },
        "shipping_method": {
          "id": "STANDARD_GROUND",
          "description": "Standard Ground Shipping",
          "price": {
            "currency": "USD",
            "value": 49.99,
            "number": 4999,
            "symbol": "$"
          },
          "estimated_delivery": "5-7 business days"
        }
      }
    ],
    "addons": {
      "offers": [
        {
          "addon_id": "bulk_discount",
          "display": {
            "name": "Bulk Purchase Discount",
            "description": "Save 5% on orders with 2+ items"
          },
          "scope": "CART",
          "price": {
            "currency": "USD",
            "value": -130.00,
            "number": -13000,
            "symbol": "$"
          }
        }
      ],
      "selections": []
    },
    "sub_total": {
      "currency": "USD",
      "value": 108.00,
      "number": 10800,
      "symbol": "$"
    },
    "shipping_total": {
      "currency": "USD",
      "value": 49.99,
      "number": 4999,
      "symbol": "$"
    },
    "tax_total": {
      "currency": "USD",
      "value": 10.80,
      "number": 1080,
      "symbol": "$"
    },
    "addon_total": {
      "currency": "USD",
      "value": 0.00,
      "number": 0,
      "symbol": "$"
    },
    "total": {
      "currency": "USD",
      "value": 168.79,
      "number": 16879,
      "symbol": "$"
    },
    "schema_version": "2.0"
  }
  ```
</ResponseExample>

## Error Responses

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

  ```json theme={null}
  {
    "code": 400,
    "error": "ErrorInvalidInputBody",
    "description": "Invalid request format"
  }
  ```
</Accordion>

<Accordion title="404 Not Found">
  Line item does not exist in the cart

  ```json theme={null}
  {
    "code": 404,
    "error": "ErrorLineItemNotFound",
    "description": "Line item does not exist"
  }
  ```
</Accordion>

<Accordion title="422 Unprocessable Entity">
  Invalid quantity or processing error

  ```json theme={null}
  {
    "code": 422,
    "error": "ErrorInvalidQuantity",
    "description": "Quantity must be non-negative"
  }
  ```
</Accordion>

## Update Behavior

<Note>
  The Update Line Item endpoint maintains cart integrity:

  * **Shipment Assignment**: Items remain in their assigned shipments after updates
  * **Empty Shipment Cleanup**: Shipments with no items are automatically removed
  * **Addon Recalculation**: Available addons may change based on new cart value
  * **Price Updates**: All totals are recalculated including shipping and tax
</Note>

## Implementation Notes

The update operation preserves the cart structure:

1. **Item Location**: The item remains in its current shipment
2. **Shipment Options**: Fulfillment and shipping options are preserved
3. **Addon State**: Selected addons remain unless they become invalid
4. **Session Continuity**: Cart session and authentication remain active

## Related Endpoints

* [Get Cart](/api-reference/cart-management/get-cart) - View current cart state
* [Add Line Item](/api-reference/cart-management/add-line-item) - Add new items to cart
* [Clear Cart](/api-reference/cart-management/clear-cart) - Empty the entire cart