---
title: "List customers"
method: GET
path: "/customers"
tags: ["Customers"]
---

# List customers

`GET /customers`

Retrieves a list of customers based on a set of provided filters.

## Query parameters

- `email` string — Filter results to only customers with the provided email address.
- `state` 'candidate' | 'member' | 'disabled' — Filter results to only customers with the provided state.
- `updated_at_min` string, date-time — Filter results to only customers updated after the provided date and time.
- `limit` integer — The maximum number of customers to retrieve.
- `cursor` string — Cursor for the page of customers to retrieve.
- `include` 'vip_status' — A comma-separated list of related objects to include in the response.

## Response `200`

The customers were successfully retrieved.

- object
  - `customers` Customer[]
    - `id` integer — Unique identifier for the customer in Smile.
    - `first_name` string, nullable — The customer's first name.
    - `last_name` string, nullable — The customer's last name.
    - `email` string — The customer's email address.
    - `state` 'candidate' | 'member' | 'disabled' — The customer's state in the loyalty program.
    - `date_of_birth` string, date, nullable — The customer's birthday. A year value of `1004` means only the customer's birth day and month was entered.
    - `points_balance` integer — The customer's current points balance.
    - `referral_url` string — The customer's unique referral URL. Used to share with friends as part of the referral program.
    - `vip_tier_id` integer, nullable — The ID of the customer's current VIP tier. This field is now deprecated, use the nested `vip_status.vip_tier_id` instead.
    - `vip_status` object — An object containing details about the customer's status within the VIP program.
      - `vip_tier_id` integer, nullable — The ID of the customer's current VIP tier.
      - `vip_tier_expires_at` string, date-time, nullable — The date the customer's current VIP tier expires. For all-time VIP programs, this will be `null` because tiers do not expire.
      - `progress_value` number, float, nullable — The amount the customer has already spent or earned within the current VIP period.
      - `current_vip_period_end` string, date-time, nullable — The end date for the current VIP period. For calendar-year VIP programs, this will be the end of the current calendar year. For all-time VIP programs, this will be `null`.
      - `delta_to_retain_vip_tier` number, float, nullable — The additional amount the customer must spend or earn before the end of the current VIP period to retain their VIP tier until the end of the next VIP period. For all-time VIP programs or if the customer has already spent or earned enough this period to retain their current VIP tier, this will be `null`.
      - `next_vip_tier_id` integer, nullable — The ID of the next VIP tier that the customer will move into if they meet the minimum spending or earning requirement. If the customer is already in the highest tier, this will be `null`.
      - `delta_to_next_vip_tier` number, float, nullable — The amount the customer must spend or earn within the current VIP period to reach the next VIP tier. If the customer is already in the highest tier, this will be `null`.
    - `created_at` string, date-time — The date and time when the customer was created.
    - `updated_at` string, date-time — The date and time when the customer was last updated.
  - `metadata` PaginationMetadata
    - `next_cursor` string, nullable — A cursor value that when present, can be used to retrieve the next page of results.
    - `previous_cursor` string, nullable — A cursor value that when present, can be used to retrieve the previous page of results.

---

[API](https://skmtc.dev/smile/apis/smile-io-rest-api.md) · [All operations](https://skmtc.dev/smile/apis/smile-io-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smile/smile-io-rest-api/revisions/081bc804c5df/schema)