> ## 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 Checkout Sessions

> Retrieve a list of checkout sessions with optional filters

<Note>
  This endpoint returns a paginated list of checkout sessions. You can filter by status, buyer email, or date range.
</Note>

## Authentication

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

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

## Query Parameters

<ParamField query="status" type="string">
  Filter by checkout status: `not_ready_for_payment`, `ready_for_payment`, `completed`, `canceled`, `in_progress`
</ParamField>

<ParamField query="buyer_email" type="string">
  Filter by buyer's email address
</ParamField>

<ParamField query="created_after" type="string">
  Filter checkouts created after this ISO 8601 timestamp
</ParamField>

<ParamField query="created_before" type="string">
  Filter checkouts created before this ISO 8601 timestamp
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page (default: 20, max: 100)
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination - ID of the last item from the previous page
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of checkout session objects
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more results available
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of checkouts matching the filters
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.stateset.com/v1/checkouts?status=ready_for_payment&limit=10' \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const checkouts = await stateset.checkouts.list({
    status: 'ready_for_payment',
    limit: 10
  });
  ```

  ```python Python theme={null}
  checkouts = stateset.checkouts.list(
      status='ready_for_payment',
      limit=10
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "data": [
      {
        "id": "checkout_abc123",
        "buyer": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone_number": "+1234567890"
        },
        "status": "ready_for_payment",
        "currency": "usd",
        "line_items": [
          {
            "id": "item_123",
            "item": {
              "id": "item_123",
              "quantity": 2
            },
            "base_amount": 2000,
            "discount": 0,
            "total": 2000,
            "subtotal": 2000,
            "tax": 0
          }
        ],
        "totals": [
          {
            "type": "total",
            "display_text": "Total",
            "amount": 2250
          }
        ],
        "created_at": "2024-09-30T10:00:00Z",
        "updated_at": "2024-09-30T10:05:00Z"
      },
      {
        "id": "checkout_def456",
        "buyer": {
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane.smith@example.com"
        },
        "status": "ready_for_payment",
        "currency": "usd",
        "line_items": [
          {
            "id": "item_789",
            "item": {
              "id": "item_789",
              "quantity": 1
            },
            "base_amount": 5000,
            "discount": 500,
            "total": 4500,
            "subtotal": 4500,
            "tax": 0
          }
        ],
        "totals": [
          {
            "type": "total",
            "display_text": "Total",
            "amount": 4800
          }
        ],
        "created_at": "2024-09-30T09:30:00Z",
        "updated_at": "2024-09-30T09:35:00Z"
      }
    ],
    "has_more": false,
    "total_count": 2
  }
  ```

  ```json Error Response - Invalid Parameter theme={null}
  {
    "success": false,
    "error": {
      "type": "invalid_request",
      "code": "INVALID_PARAMETER",
      "message": "Invalid status value provided",
      "param": "status"
    }
  }
  ```
</ResponseExample>