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

# List Customers

> Retrieve all customers from your store

Retrieves a cursor-paginated list of all customers in your store. Customers are created automatically when they make a purchase. This endpoint supports search filtering and date range filtering.

## Query Parameters

<ParamField query="per_page" type="integer" default="15">
  Number of customers to return per page (max 100)
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination. Use the `next_cursor` from the previous response.
</ParamField>

<ParamField query="search" type="string">
  Search customers by name, email, or phone number
</ParamField>

<ParamField query="start_date" type="string">
  Filter customers created from this date (Y-m-d format, e.g., `2025-01-01`)
</ParamField>

<ParamField query="end_date" type="string">
  Filter customers created until this date (Y-m-d format, e.g., `2025-01-31`)
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="data" type="array">
      Array of customer objects

      <Expandable title="customer object">
        <ResponseField name="id" type="string">
          Unique customer identifier (e.g., `cus_abc123xyz`)
        </ResponseField>

        <ResponseField name="name" type="string">
          Customer full name (combination of first and last name)
        </ResponseField>

        <ResponseField name="first_name" type="string">
          Customer first name
        </ResponseField>

        <ResponseField name="last_name" type="string">
          Customer last name
        </ResponseField>

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

        <ResponseField name="avatar_url" type="string">
          URL to the customer's avatar image
        </ResponseField>

        <ResponseField name="phone" type="object">
          Customer phone number

          <Expandable title="phone object">
            <ResponseField name="number" type="string">
              International formatted phone number (e.g., `+1 234 567 890`)
            </ResponseField>

            <ResponseField name="country" type="object">
              Country information

              <Expandable title="country object">
                <ResponseField name="name" type="string">
                  Country name
                </ResponseField>

                <ResponseField name="code" type="string">
                  ISO 3166-1 alpha-2 country code
                </ResponseField>

                <ResponseField name="alpha_3_code" type="string">
                  ISO 3166-1 alpha-3 country code
                </ResponseField>

                <ResponseField name="dial_code" type="string">
                  Country dial code
                </ResponseField>

                <ResponseField name="currency" type="string">
                  Country currency code
                </ResponseField>

                <ResponseField name="flag" type="string">
                  Country flag emoji
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="store" type="object">
          Store information

          <Expandable title="store object">
            <ResponseField name="id" type="string">
              Store public ID
            </ResponseField>

            <ResponseField name="name" type="string">
              Store name
            </ResponseField>

            <ResponseField name="logo_url" type="string">
              Store logo URL
            </ResponseField>

            <ResponseField name="url" type="string">
              Store URL
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the customer was created
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          ISO 8601 timestamp of when the customer was last updated
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Cursor pagination metadata

      <Expandable title="pagination object">
        <ResponseField name="next_cursor" type="string">
          Cursor for the next page (null if no more pages)
        </ResponseField>

        <ResponseField name="prev_cursor" type="string">
          Cursor for the previous page (null if on first page)
        </ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/customers?per_page=20&search=john" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chariow.com/v1/customers?per_page=20&search=john', {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key'
    }
  });

  const { data } = await response.json();
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.chariow.com/v1/customers?per_page=20&search=john');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer sk_live_your_api_key'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  $data = json_decode($response, true);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.chariow.com/v1/customers',
      params={'per_page': 20, 'search': 'john'},
      headers={'Authorization': 'Bearer sk_live_your_api_key'}
  )

  data = response.json()['data']
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "success",
    "data": {
      "data": [
        {
          "id": "cus_abc123xyz",
          "name": "John Doe",
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "avatar_url": "https://cdn.chariow.com/avatars/abc123.jpg",
          "phone": {
            "number": "+1 234 567 890",
            "country": {
              "name": "United States",
              "code": "US",
              "alpha_3_code": "USA",
              "dial_code": "+1",
              "currency": "USD",
              "flag": "🇺🇸"
            }
          },
          "store": {
            "id": "str_xyz789",
            "name": "My Digital Store",
            "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
            "url": "https://mystore.chariow.link"
          },
          "created_at": "2025-01-15T10:30:00+00:00",
          "updated_at": "2025-01-20T14:45:00+00:00"
        }
      ],
      "pagination": {
        "next_cursor": "eyJpZCI6NTB9",
        "prev_cursor": null,
        "has_more": true
      }
    },
    "errors": []
  }
  ```
</ResponseExample>