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

> Retrieve a paginated list of customers with optional filtering and sorting

<Note>
  Returns a paginated array of customer objects. Use query parameters to filter, sort, and paginate results.
</Note>

## Query Parameters

<ParamField query="limit" type="integer" default="20">
  Maximum number of customers to return per page. Range: 1-100.

  **Example:** `50`
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of records to skip for pagination.

  **Example:** `20`
</ParamField>

<ParamField query="order_direction" type="string" default="desc">
  Sort direction for results. Options: `asc`, `desc`.
</ParamField>

<ParamField query="email" type="string">
  Filter customers by email address (exact match).

  **Example:** `jane.doe@example.com`
</ParamField>

<ParamField query="created_after" type="string">
  Filter customers created after this ISO 8601 date.

  **Example:** `2024-01-01T00:00:00.000Z`
</ParamField>

### Response

<ResponseField name="customers" type="array">
  Array of customer objects.

  <Expandable title="Customer Object">
    <ResponseField name="sso_id" type="string">
      Unique identifier for the customer.
    </ResponseField>

    <ResponseField name="email" type="string">
      Customer's email address.
    </ResponseField>

    <ResponseField name="firstName" type="string">
      Customer's first name.
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Customer's last name.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Customer's phone number.
    </ResponseField>

    <ResponseField name="stripe_customer_id" type="string">
      Associated Stripe customer ID.
    </ResponseField>

    <ResponseField name="activationDate" type="string">
      ISO 8601 date when the customer account was activated.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the last update.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of customers matching the query.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more results beyond the current page.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.stateset.com/v1/customers?limit=20&offset=0&order_direction=desc' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'
  ```

  ```graphql GraphQL theme={null}
  query listCustomers($limit: Int!, $offset: Int!) {
    customers(limit: $limit, offset: $offset, order_by: { timestamp: desc }) {
      sso_id
      activationDate
      email
      firstName
      lastName
      phone
      stripe_customer_id
      timestamp
    }
    customers_aggregate {
      aggregate {
        count
      }
    }
  }
  ```

  ```javascript Node.js theme={null}
  const customers = await stateset.customers.list({
    limit: 20,
    offset: 0,
    order_direction: 'desc',
  });
  ```

  ```python Python theme={null}
  customers = stateset.customers.list(
    limit=20,
    offset=0,
    order_direction='desc',
  )
  ```

  ```ruby Ruby theme={null}
  customers = Stateset::Customers.list(
    limit: 20,
    offset: 0,
    order_direction: 'desc',
  )
  ```

  ```go Go theme={null}
  customers, err := stateset.Customers.List(&CustomerListParams{
    Limit:          20,
    Offset:         0,
    OrderDirection: "desc",
  })
  ```

  ```php PHP theme={null}
  $customers = $stateset->customers->list([
    'limit' => 20,
    'offset' => 0,
    'order_direction' => 'desc',
  ]);
  ```

  ```java Java theme={null}
  CustomerCollection customers = stateset.customers().list(
    CustomerListParams.builder()
      .setLimit(20)
      .setOffset(0)
      .setOrderDirection("desc")
      .build()
  );
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "customers": [
      {
        "sso_id": "1234-5678-9012-3456",
        "email": "jane.doe@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1-555-123-4567",
        "stripe_customer_id": "cus_1234567890",
        "activationDate": "2024-01-15T00:00:00.000Z",
        "timestamp": "2024-06-01T12:30:00.000Z"
      },
      {
        "sso_id": "9876-5432-1098-7654",
        "email": "john.smith@example.com",
        "firstName": "John",
        "lastName": "Smith",
        "phone": "+1-555-987-6543",
        "stripe_customer_id": "cus_0987654321",
        "activationDate": "2024-02-20T00:00:00.000Z",
        "timestamp": "2024-05-28T09:15:00.000Z"
      }
    ],
    "total_count": 142,
    "has_more": true
  }
  ```

  ```json Error Response (400 Bad Request) theme={null}
  {
    "error": {
      "code": "INVALID_PARAMETER",
      "message": "limit must be between 1 and 100",
      "details": {
        "parameter": "limit",
        "value": 500
      },
      "request_id": "req_abc123def456"
    }
  }
  ```

  ```json Error Response (401 Unauthorized) theme={null}
  {
    "error": {
      "code": "INVALID_API_KEY",
      "message": "The API key provided is invalid or has been revoked",
      "request_id": "req_abc123def456"
    }
  }
  ```
</ResponseExample>