Skip to main content
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:

Line Items

Individual products with quantities, pricing, and metadata

Shipments

Items grouped based on merchant-defined fulfillment rules

Pricing

Calculated subtotal, shipping, tax, addon costs, and total

Addons

Available and selected value-added services

​
Merchant Integration

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.

​
Available Endpoints

Get Cart

Retrieve the current cart state with all items, shipments, and pricing

Add Line Item

Add new products to the cart

Update Line Item

Modify quantities or remove items from the cart

Clear Cart

Remove all items from the cart

​
Typical Cart Flow

1

Initialize Cart

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

Add Items

Use Add Line Item endpoint to add products with SKU, quantity, and price
3

Review Cart

Get Cart returns complete state including shipments and pricing
4

Modify as Needed

Update quantities or remove items using Update Line Item
5

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

{
  "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

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

{
  "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

GET /api/v2/domains/staging.luma.gift/cart
Response shows items organized into shipments: 
{
  "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

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

​
Error Handling

Common errors when managing carts:
Error CodeDescriptionResolution
InvalidSKUProduct SKU not foundVerify SKU exists in merchant catalog
InvalidQuantityQuantity less than or equal to 0 or non-integerUse positive integer quantities
CartNotFoundCart doesn’t existCart may have expired, start new session
MerchantErrorMerchant system returned an errorCheck merchant-specific error details

​
Next Steps

Once your cart is built:

Configure Shipments

Set fulfillment types and shipping methods

Apply Addons

Offer value-added services to customers