> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Cart

> Create a new shopping cart for a customer or guest session

<Note>
  This endpoint creates a new shopping cart that persists across sessions. Carts can be associated with authenticated customers or anonymous sessions.
</Note>

## Authentication

This endpoint requires a valid API key with `carts:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="customer_id" type="string">
  Customer ID to associate with the cart (for authenticated users)
</ParamField>

<ParamField body="session_id" type="string">
  Session ID for guest carts (auto-generated if not provided)
</ParamField>

<ParamField body="channel" type="string">
  Sales channel: "web", "mobile", "pos", "api"
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code
</ParamField>

<ParamField body="locale" type="string">
  Locale for the cart (e.g., "en-US")
</ParamField>

<ParamField body="items" type="array">
  Initial items to add to the cart

  <Expandable title="Item properties">
    <ParamField body="product_id" type="string" required>
      Product ID
    </ParamField>

    <ParamField body="variant_id" type="string">
      Product variant ID
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity to add
    </ParamField>

    <ParamField body="price_override" type="integer">
      Override price in cents (for custom pricing)
    </ParamField>

    <ParamField body="metadata" type="object">
      Custom fields for the item
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping_address" type="object">
  Shipping address for tax/shipping calculations

  <Expandable title="Address properties">
    <ParamField body="line1" type="string">
      Street address
    </ParamField>

    <ParamField body="line2" type="string">
      Apartment, suite, etc.
    </ParamField>

    <ParamField body="city" type="string">
      City
    </ParamField>

    <ParamField body="state" type="string">
      State/Province code
    </ParamField>

    <ParamField body="postal_code" type="string">
      Postal/ZIP code
    </ParamField>

    <ParamField body="country" type="string">
      ISO 3166-1 alpha-2 country code
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="email" type="string">
  Email for guest checkout and abandoned cart recovery
</ParamField>

<ParamField body="expires_at" type="string">
  Custom expiration date (ISO 8601, default: 30 days)
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created cart object.

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
  }'
  ```

  ```javascript Node.js theme={null}
  const cart = await stateset.carts.create({
    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"
    }
  });
  ```

  ```python Python theme={null}
  cart = stateset.carts.create(
    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"
    }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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": {}
  }
  ```
</ResponseExample>