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

# Overview

> Endpoints for managing shopping carts

The Cart Management API provides core operations for creating and managing shopping carts. These endpoints handle adding items, updating quantities, and clearing cart contents.

## Overview

Cart Management provides:

* **Real-time Merchant Integration**: All operations are transmitted to merchant systems in real-time
* **Session-based Cart Management**: Carts are managed through device-based authentication
* **Multi-shipment Support**: Items are organized into shipments based on merchant configuration
* **Automatic Pricing**: Price calculations including tax and shipping from merchant systems

## Key Concepts

### Cart Structure

Carts contain:

<CardGroup cols={2}>
  <Card title="Line Items" icon="list">
    Individual products with quantities, pricing, and metadata
  </Card>

  <Card title="Shipments" icon="truck">
    Items grouped based on merchant-defined fulfillment rules
  </Card>

  <Card title="Pricing" icon="dollar">
    Calculated subtotal, shipping, tax, addon costs, and total
  </Card>

  <Card title="Addons" icon="plus">
    Available and selected value-added services
  </Card>
</CardGroup>

### Merchant Integration

<Note>
  All cart operations are processed through the merchant's systems in real-time. Firmly acts as a unified interface to the merchant's cart functionality.
</Note>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Get Cart" icon="eye" href="/api-reference/cart-management/get-cart">
    Retrieve the current cart state with all items, shipments, and pricing
  </Card>

  <Card title="Add Line Item" icon="plus" href="/api-reference/cart-management/add-line-item">
    Add new products to the cart
  </Card>

  <Card title="Update Line Item" icon="pencil" href="/api-reference/cart-management/update-line-item">
    Modify quantities or remove items from the cart
  </Card>

  <Card title="Clear Cart" icon="trash" href="/api-reference/cart-management/clear-cart">
    Remove all items from the cart
  </Card>
</CardGroup>

## Typical Cart Flow

<Steps>
  <Step title="Initialize Cart">
    Cart is automatically created on first item addition or can be retrieved if exists
  </Step>

  <Step title="Add Items">
    Use Add Line Item endpoint to add products with SKU, quantity, and price
  </Step>

  <Step title="Review Cart">
    Get Cart returns complete state including shipments and pricing
  </Step>

  <Step title="Modify as Needed">
    Update quantities or remove items using Update Line Item
  </Step>

  <Step title="Proceed to Checkout">
    Once cart is finalized, move to shipment configuration and checkout
  </Step>
</Steps>

## Example: Building a Cart

### 1. Add First Item

```bash theme={null}
POST /api/v2/domains/staging.luma.gift/cart/line-items
```

```json theme={null}
{
  "sku": "MH07-XS-Gray",
  "variant_id": "MH07-XS-Gray",
  "quantity": 1,
  "price": {
    "currency": "USD",
    "value": 54.00
  },
  "description": "Hero Hoodie - Gray XS"
}
```

### 2. Add Another Item

```bash theme={null}
POST /api/v2/domains/staging.luma.gift/cart/line-items
```

```json theme={null}
{
  "sku": "WS12-XS-Orange",
  "variant_id": "WS12-XS-Orange",
  "quantity": 2,
  "price": {
    "currency": "USD",
    "value": 22.00
  },
  "description": "Radiant Tee - Orange XS"
}
```

### 3. Review Cart State

```bash theme={null}
GET /api/v2/domains/staging.luma.gift/cart
```

Response shows items organized into shipments:

```json theme={null}
{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "line_items": [
    {
      "line_item_id": "item_001",
      "sku": "MH07-XS-Gray",
      "quantity": 1,
      "price": { "value": 54.00 }
    },
    {
      "line_item_id": "item_002", 
      "sku": "WS12-XS-Orange",
      "quantity": 2,
      "price": { "value": 22.00 }
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_001",
      "line_item_ids": ["item_001", "item_002"],
      "fulfillment_type": null,
      "shipping_method": null
    }
  ],
  "sub_total": { "value": 98.00 },
  "total": { "value": 98.00 }
}
```

## Important Behaviors

<Note>
  * Items are assigned to shipments based on merchant rules
  * Shipment groupings are determined by the merchant's system
  * Price calculations happen through the merchant's pricing engine
  * Cart state persists based on merchant configuration
</Note>

<Warning>
  **Validation Rules:**

  * SKUs must exist in the merchant's catalog
  * Quantities must be positive integers
  * Prices should match catalog prices (mismatches may be handled per merchant rules)
  * All validations are performed by the merchant's system
</Warning>

## Error Handling

Common errors when managing carts:

| Error Code        | Description                                     | Resolution                               |
| ----------------- | ----------------------------------------------- | ---------------------------------------- |
| `InvalidSKU`      | Product SKU not found                           | Verify SKU exists in merchant catalog    |
| `InvalidQuantity` | Quantity less than or equal to 0 or non-integer | Use positive integer quantities          |
| `CartNotFound`    | Cart doesn't exist                              | Cart may have expired, start new session |
| `MerchantError`   | Merchant system returned an error               | Check merchant-specific error details    |

## Next Steps

Once your cart is built:

<CardGroup cols={2}>
  <Card title="Configure Shipments" icon="truck" href="/api-reference/shipment-configuration/overview">
    Set fulfillment types and shipping methods
  </Card>

  <Card title="Apply Addons" icon="plus" href="/api-reference/addon-management/overview">
    Offer value-added services to customers
  </Card>
</CardGroup>