**版本：202601**

# 查询顾客列表

**GET** `/openapi/2026-01/customers`

分页返回顾客列表。

## 请求

**Query参数**

- `cursor` string

  分页游标
- `page_size` int32

  每页记录数
- `page` int32

  页码（从 1 开始），与 cursor 互斥
- `ids` string[]

  ID 列表。 示例：?ids=1001&ids=1002
- `created_at_min` string

  最早创建时间
- `created_at_max` string

  最晚创建时间
- `updated_at_min` string

  最早更新时间
- `updated_at_max` string

  最晚更新时间
- `email` string

  电子邮件地址
- `contact` string

  联系方式类型

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `customers` object[]

    顾客列表

    *   Array \[

    - `id` string

      顾客的唯一标识
    - `email` string

      顾客的电子邮件地址
    - `created_at` string

      顾客创建时间，ISO-8601 格式
    - `updated_at` string

      顾客最后更新时间，ISO-8601 格式
    - `first_name` string

      顾客的名
    - `last_name` string

      顾客的姓
    - `phone` string

      顾客的电话号码
    - `tags` string[]

      顾客标签
    - `name` string

      顾客的名字
    - `phone_area_code` string

      电话号码的区号
    - `contact_type` string

      联系方式类型，邮箱或电话
    - `sms_subscribed_flag` int32

      顾客的短信订阅状态标志
    - `addresses` object[]

      顾客的所有地址列表

      *   Array \[

      - `id` string

        地址的唯一标识
      - `customer_id` string

        顾客 ID
      - `first_name` string

        收件人的名
      - `last_name` string

        收件人的姓
      - `company` string

        公司名称
      - `city` string

        地址所在城市
      - `province` string

        地址所在省份或州
      - `country` string

        地址所在国家名称
      - `zip` string

        邮政编码
      - `province_code` string

        省份代码
      - `country_code` string

        ISO 国家代码
      - `gender` string

        收件人的性别
      - `phone` string

        与地址关联的电话号码
      - `phone_area_code` string

        电话号码的区号
      - `area` string

        地址所在区域或地区
      - `email` string

        与地址关联的电子邮件
      - `name` string

        收件人的全名
      - `address1` string

        地址1
      - `address2` string

        地址2
      - `country_name` string

        国家全称
      - `default` boolean

        是否为默认地址
      *   \]
    - `accepts_marketing` boolean

      顾客是否订阅了营销邮件
    - `source` string

      顾客数据来源
    - `free_tax` boolean

      顾客是否享有税收豁免
    - `registered` boolean

      顾客是否已注册
    - `orders_count` int32

      顾客的累计下单数量
    - `first_order_at` string

      首次下单时间
    - `last_order_at` string

      顾客最后一次下单时间
    - `total_spent` string

      顾客的累计消费金额
    - `subscribed_flag` int32

      顾客的营销订阅状态
    - `accepts_sms_marketing` boolean

      顾客是否订阅了短信营销活动
    *   \]
  - `cursor` string

    分页游标
  - `has_more` boolean

    是否有更多记录

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "customers": [
      {
        "id": "string",
        "email": "string",
        "created_at": "string",
        "updated_at": "string",
        "first_name": "string",
        "last_name": "string",
        "phone": "string",
        "tags": [
          "string"
        ],
        "name": "string",
        "phone_area_code": "string",
        "contact_type": "string",
        "sms_subscribed_flag": 0,
        "addresses": [
          {
            "id": "string",
            "customer_id": "string",
            "first_name": "string",
            "last_name": "string",
            "company": "string",
            "city": "string",
            "province": "string",
            "country": "string",
            "zip": "string",
            "province_code": "string",
            "country_code": "string",
            "gender": "string",
            "phone": "string",
            "phone_area_code": "string",
            "area": "string",
            "email": "string",
            "name": "string",
            "address1": "string",
            "address2": "string",
            "country_name": "string",
            "default": true
          }
        ],
        "accepts_marketing": true,
        "source": "string",
        "free_tax": true,
        "registered": true,
        "orders_count": 0,
        "first_order_at": "string",
        "last_order_at": "string",
        "total_spent": "string",
        "subscribed_flag": 0,
        "accepts_sms_marketing": true
      }
    ],
    "cursor": "string",
    "has_more": true
  }
}
```