GET /api/cart

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "createdAt": "2023-04-15T10:30:00Z",
  "updatedAt": "2023-04-16T08:45:00Z",
  "items": [
    {
      "id": "item_123456",
      "productId": "prod_123456",
      "variantId": "var_789012",
      "name": "Serenity Candle",
      "variantName": "Small",
      "sku": "SER-CAN-S",
      "price": 24.99,
      "quantity": 1,
      "image": "https://example.com/images/candle1.jpg",
      "customizations": {
        "fragrance": "standard",
        "giftWrapped": false
      }
    },
    {
      "id": "item_123457",
      "productId": "prod_234567",
      "variantId": "var_789014",
      "name": "Lavender Bath Bombs",
      "variantName": "3-Pack",
      "sku": "LAV-BB-3P",
      "price": 34.99,
      "quantity": 1,
      "image": "https://example.com/images/bath-bomb-pack.jpg",
      "customizations": {
        "giftWrapped": true,
        "giftMessage": "Happy Birthday!"
      }
    }
  ],
  "itemCount": 2,
  "subtotal": 59.98,
  "discounts": [
    {
      "code": "WELCOME10",
      "description": "10% off your first order",
      "type": "percentage",
      "value": 10,
      "amount": 5.99
    }
  ],
  "discountTotal": 5.99,
  "estimatedTax": 5.40,
  "estimatedTotal": 59.39,
  "currency": "USD",
  "notes": "Please gift wrap the Lavender Bath Bombs"
}

POST /api/cart/items

{
  "productId": "prod_345678",
  "variantId": "var_901234",
  "quantity": 1,
  "customizations": {
    "fragrance": "custom",
    "fragranceId": "scent_123456",
    "giftWrapped": true,
    "giftMessage": "Enjoy your custom fragrance!"
  }
}

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Existing items...
    {
      "id": "item_123458",
      "productId": "prod_345678",
      "variantId": "var_901234",
      "name": "Custom Blend Diffuser",
      "variantName": "Medium",
      "sku": "CBD-MED",
      "price": 39.99,
      "quantity": 1,
      "image": "https://example.com/images/diffuser1.jpg",
      "customizations": {
        "fragrance": "custom",
        "fragranceId": "scent_123456",
        "fragranceName": "Summer Breeze",
        "giftWrapped": true,
        "giftMessage": "Enjoy your custom fragrance!"
      }
    }
  ],
  "itemCount": 3,
  "subtotal": 99.97,
  "discountTotal": 5.99,
  "estimatedTax": 9.40,
  "estimatedTotal": 103.38,
  "currency": "USD",
  "updatedAt": "2023-04-16T09:15:00Z"
}

PATCH /api/cart/items/{itemId}

{
  "quantity": 2,
  "customizations": {
    "giftWrapped": false
  }
}

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Other items...
    {
      "id": "item_123458",
      "productId": "prod_345678",
      "variantId": "var_901234",
      "name": "Custom Blend Diffuser",
      "variantName": "Medium",
      "sku": "CBD-MED",
      "price": 39.99,
      "quantity": 2,
      "image": "https://example.com/images/diffuser1.jpg",
      "customizations": {
        "fragrance": "custom",
        "fragranceId": "scent_123456",
        "fragranceName": "Summer Breeze",
        "giftWrapped": false
      }
    },
    // Other items...
  ],
  "itemCount": 4,
  "subtotal": 139.96,
  "discountTotal": 5.99,
  "estimatedTax": 13.40,
  "estimatedTotal": 147.37,
  "currency": "USD",
  "updatedAt": "2023-04-16T09:20:00Z"
}

DELETE /api/cart/items/{itemId}

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Remaining items after removal
  ],
  "itemCount": 2,
  "subtotal": 59.98,
  "discountTotal": 5.99,
  "estimatedTax": 5.40,
  "estimatedTotal": 59.39,
  "currency": "USD",
  "updatedAt": "2023-04-16T09:25:00Z"
}

POST /api/cart/discounts

{
  "code": "SPRING20"
}

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Cart items...
  ],
  "itemCount": 2,
  "subtotal": 59.98,
  "discounts": [
    {
      "code": "SPRING20",
      "description": "20% off spring collection",
      "type": "percentage",
      "value": 20,
      "amount": 12.00
    }
  ],
  "discountTotal": 12.00,
  "estimatedTax": 4.80,
  "estimatedTotal": 52.78,
  "currency": "USD",
  "updatedAt": "2023-04-16T09:30:00Z"
}

DELETE /api/cart/discounts/{code}

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Cart items...
  ],
  "itemCount": 2,
  "subtotal": 59.98,
  "discounts": [],
  "discountTotal": 0.00,
  "estimatedTax": 6.00,
  "estimatedTotal": 65.98,
  "currency": "USD",
  "updatedAt": "2023-04-16T09:35:00Z"
}

POST /api/cart/notes

{
  "note": "Please deliver on weekdays only"
}

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Cart items...
  ],
  "notes": "Please deliver on weekdays only",
  "updatedAt": "2023-04-16T09:40:00Z"
}

POST /api/cart/shipping-estimates

{
  "address": {
    "postalCode": "10001",
    "country": "US",
    "state": "NY"
  }
}

{
  "estimates": [
    {
      "method": "standard",
      "carrier": "USPS",
      "cost": 5.99,
      "estimatedDelivery": "5-7 business days",
      "estimatedDeliveryMin": "2023-04-21",
      "estimatedDeliveryMax": "2023-04-25"
    },
    {
      "method": "express",
      "carrier": "UPS",
      "cost": 9.99,
      "estimatedDelivery": "2-3 business days",
      "estimatedDeliveryMin": "2023-04-18",
      "estimatedDeliveryMax": "2023-04-19"
    },
    {
      "method": "overnight",
      "carrier": "FedEx",
      "cost": 19.99,
      "estimatedDelivery": "Next business day",
      "estimatedDeliveryMin": "2023-04-17",
      "estimatedDeliveryMax": "2023-04-17"
    }
  ],
  "freeShippingEligible": false,
  "freeShippingThreshold": 75.00,
  "amountToFreeShipping": 15.02
}

POST /api/cart/checkout

{
  "id": "cart_123456",
  "customerId": "user_123456",
  "items": [
    // Cart items...
  ],
  "itemCount": 2,
  "subtotal": 59.98,
  "discountTotal": 0.00,
  "estimatedTax": 6.00,
  "estimatedTotal": 65.98,
  "currency": "USD",
  "checkoutId": "checkout_123456",
  "checkoutExpires": "2023-04-16T10:10:00Z",
  "inventoryReserved": true,
  "readyForCheckout": true
}