POST
/
v1
/
carts
curl --location --request POST 'https://api.stateset.com/v1/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "customer_id": "cust_abc123",
    "channel": "web",
    "currency": "USD",
    "locale": "en-US",
    "items": [
        {
            "product_id": "prod_123",
            "variant_id": "var_blue_large",
            "quantity": 2
        }
    ],
    "shipping_address": {
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}'

{
  "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "cart",
  "customer_id": "cust_abc123",
  "session_id": "sess_xyz789",
  "channel": "web",
  "currency": "USD",
  "locale": "en-US",
  "status": "active",
  "items": [
    {
      "id": "ci_abc123",
      "product_id": "prod_123",
      "variant_id": "var_blue_large",
      "product_name": "Wireless Headphones",
      "variant_name": "Blue - Large",
      "sku": "WH-BL-L",
      "quantity": 2,
      "unit_price": 9999,
      "list_price": 9999,
      "subtotal": 19998,
      "discounts": [],
      "image_url": "https://images.stateset.com/products/wh-blue-large.jpg",
      "metadata": {}
    }
  ],
  "item_count": 2,
  "unique_item_count": 1,
  "subtotal": 19998,
  "tax_amount": 0,
  "shipping_amount": 0,
  "discount_amount": 0,
  "total": 19998,
  "shipping_address": {
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "available_shipping_methods": [],
  "applied_coupons": [],
  "applied_promotions": [],
  "expires_at": "2024-07-20T10:00:00Z",
  "created_at": "2024-06-20T10:00:00Z",
  "updated_at": "2024-06-20T10:00:00Z",
  "metadata": {}
}
This endpoint creates a new shopping cart that persists across sessions. Carts can be associated with authenticated customers or anonymous sessions.

​
Authentication

This endpoint requires a valid API key with carts:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
customer_id
string
Customer ID to associate with the cart (for authenticated users)
​
session_id
string
Session ID for guest carts (auto-generated if not provided)
​
channel
string
Sales channel: “web”, “mobile”, “pos”, “api”
​
currency
string
required
ISO 4217 currency code
​
locale
string
Locale for the cart (e.g., “en-US”)
​
items
array
Initial items to add to the cart
​
shipping_address
object
Shipping address for tax/shipping calculations
​
email
string
Email for guest checkout and abandoned cart recovery
​
expires_at
string
Custom expiration date (ISO 8601, default: 30 days)
​
metadata
object
Additional custom fields

​
Response

Returns the created cart object. 
curl --location --request POST 'https://api.stateset.com/v1/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "customer_id": "cust_abc123",
    "channel": "web",
    "currency": "USD",
    "locale": "en-US",
    "items": [
        {
            "product_id": "prod_123",
            "variant_id": "var_blue_large",
            "quantity": 2
        }
    ],
    "shipping_address": {
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}'

{
  "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "cart",
  "customer_id": "cust_abc123",
  "session_id": "sess_xyz789",
  "channel": "web",
  "currency": "USD",
  "locale": "en-US",
  "status": "active",
  "items": [
    {
      "id": "ci_abc123",
      "product_id": "prod_123",
      "variant_id": "var_blue_large",
      "product_name": "Wireless Headphones",
      "variant_name": "Blue - Large",
      "sku": "WH-BL-L",
      "quantity": 2,
      "unit_price": 9999,
      "list_price": 9999,
      "subtotal": 19998,
      "discounts": [],
      "image_url": "https://images.stateset.com/products/wh-blue-large.jpg",
      "metadata": {}
    }
  ],
  "item_count": 2,
  "unique_item_count": 1,
  "subtotal": 19998,
  "tax_amount": 0,
  "shipping_amount": 0,
  "discount_amount": 0,
  "total": 19998,
  "shipping_address": {
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "available_shipping_methods": [],
  "applied_coupons": [],
  "applied_promotions": [],
  "expires_at": "2024-07-20T10:00:00Z",
  "created_at": "2024-06-20T10:00:00Z",
  "updated_at": "2024-06-20T10:00:00Z",
  "metadata": {}
}