> ## 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.

# List Carts

> List all carts with filtering and pagination options

<Note>
  This endpoint returns a paginated list of carts. You can filter by customer, status, date range, and more. Useful for abandoned cart recovery and analytics.
</Note>

## Authentication

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

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

## Query Parameters

<ParamField query="limit" type="integer" default="10">
  Number of carts to return (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of carts to skip
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by customer ID
</ParamField>

<ParamField query="session_id" type="string">
  Filter by session ID
</ParamField>

<ParamField query="status" type="string">
  Filter by status: "active", "abandoned", "converted", "expired"
</ParamField>

<ParamField query="channel" type="string">
  Filter by channel: "web", "mobile", "pos", "api"
</ParamField>

<ParamField query="created_after" type="string">
  Filter carts created after date (ISO 8601)
</ParamField>

<ParamField query="created_before" type="string">
  Filter carts created before date (ISO 8601)
</ParamField>

<ParamField query="updated_after" type="string">
  Filter carts updated after date (ISO 8601)
</ParamField>

<ParamField query="has_email" type="boolean">
  Filter carts with email addresses (for recovery)
</ParamField>

<ParamField query="min_value" type="integer">
  Minimum cart value in cents
</ParamField>

<ParamField query="sort_by" type="string" default="updated_at">
  Sort by field: "created\_at", "updated\_at", "total", "abandoned\_at"
</ParamField>

<ParamField query="sort_order" type="string" default="desc">
  Sort order: "asc" or "desc"
</ParamField>

### Response

Returns a paginated list of cart objects.

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/carts?status=abandoned&has_email=true&limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const carts = await stateset.carts.list({
    status: 'abandoned',
    has_email: true,
    limit: 20
  });
  ```

  ```python Python theme={null}
  carts = stateset.carts.list(
    status='abandoned',
    has_email=True,
    limit=20
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "cart_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
        "object": "cart",
        "customer_id": "cust_abc123",
        "email": "john@example.com",
        "status": "abandoned",
        "channel": "web",
        "currency": "USD",
        "item_count": 3,
        "subtotal": 34495,
        "total": 37762,
        "abandoned_at": "2024-06-19T20:00:00Z",
        "last_activity": "2024-06-19T19:30:00Z",
        "created_at": "2024-06-19T18:00:00Z",
        "recovery_status": "not_attempted"
      },
      {
        "id": "cart_1234f083-bb2d-54d6-bg6d-1b0e3gd75f41",
        "object": "cart",
        "customer_id": null,
        "email": "jane@example.com",
        "status": "abandoned",
        "channel": "mobile",
        "currency": "USD",
        "item_count": 1,
        "subtotal": 4999,
        "total": 5648,
        "abandoned_at": "2024-06-18T15:00:00Z",
        "last_activity": "2024-06-18T14:45:00Z",
        "created_at": "2024-06-18T14:00:00Z",
        "recovery_status": "email_sent"
      }
    ],
    "has_more": true,
    "total_count": 156,
    "url": "/v1/carts",
    "summary": {
      "total_abandoned_value": 2847532,
      "average_cart_value": 18252,
      "recovery_rate": 0.23,
      "status_breakdown": {
        "active": 45,
        "abandoned": 156,
        "converted": 1234,
        "expired": 89
      }
    }
  }
  ```
</ResponseExample>