Cart Management

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
• Merchant-sourced pricing: Prices, tax, and shipping totals are calculated by the merchant’s platform and returned in the cart

​​ Key Concepts

​​ Cart Structure

Carts contain:

​​ Merchant Integration

​​ Available Endpoints

​​ Typical Cart Flow

​​ Initialize Cart

Cart is automatically created on first item addition or can be retrieved if one exists

​​ Add Items

Use Add Line Item endpoint to add products with a variant_id (inside add_to_cart_ref) and quantity. Price, description, and other product metadata are resolved server-side from the merchant catalog.

​​ Review Cart

Get Cart returns complete state including shipments and pricing

​​ Modify as Needed

Update quantities or remove items using Update Line Item

​​ Proceed to Checkout

Once cart is finalized, move to shipment configuration and checkout

​​ Example: Building a Cart

​​ 1. Add First Item

POST /api/v2/domains/staging.luma.gift/cart/line-items

Request body:

{
  "add_to_cart_ref": {
    "variant_id": "MH07-XS-Gray"
  },
  "quantity": 1
}

​​ 2. Add Another Item

POST /api/v2/domains/staging.luma.gift/cart/line-items

Request body:

{
  "add_to_cart_ref": {
    "variant_id": "WS12-XS-Orange"
  },
  "quantity": 2
}

​​ 3. Review Cart State

GET /api/v2/domains/staging.luma.gift/cart

Response — line items with price and description resolved from the merchant catalog. Shipments are populated only after a shipping address is set (see Set Shipping Info), so shipments is empty at this stage:

{
  "cart_id": "a5600193-2c13-3356-d063-711da63b7cd7",
  "line_items": [
    {
      "line_item_id": "380c6749-dc4f-7c63-f049-847e3862f396",
      "sku": "MH07-XS-Gray",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.0,
        "number": 5400,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 54.0,
        "number": 5400,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 64.8,
        "number": 6480,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/mh07-xs-gray.jpg",
        "alt": "MH07-XS-Gray",
        "type": "default"
      }
    },
    {
      "line_item_id": "d3e502a4-1fc8-e244-532c-4f5ffbcfc4d8",
      "sku": "WS12-XS-Orange",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 22.0,
        "number": 2200,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 44.0,
        "number": 4400,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 26.4,
        "number": 2640,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/ws12-xs-orange.jpg",
        "alt": "WS12-XS-Orange",
        "type": "default"
      }
    }
  ],
  "shipments": [],
  "sub_total": {
    "currency": "USD",
    "value": 98.0,
    "number": 9800,
    "symbol": "$"
  },
  "fees": [
    {
      "description": "Recycle fee",
      "currency": "USD",
      "value": 2.00,
      "number": 200,
      "symbol": "$"
    }
  ],
  "fee_total": {
    "currency": "USD",
    "value": 2.00,
    "number": 200,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 100.00,
    "number": 10000,
    "symbol": "$"
  }
}

​​ Validation

• variant_id must exist in the merchant’s catalog
• quantity must be a positive integer (>= 1)
• Stock, availability, and eligibility are validated against the merchant in real time

​​ Next Steps

Once your cart is built:

​​ Error Handling

The error field in the response body identifies the failure. Common errors when managing carts: