**Version: 202601**

# List customers

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

Retrieve a list of all customers with pagination.

## Request

**Query Parameters**

- `cursor` string

  The cursor for pagination
- `page_size` int32

  The number of customers to retrieve per page. The default is 10, and the maximum is 250
- `page` int32

  Page number (1-based). Mutually exclusive with cursor
- `ids` string[]

  A list of customer IDs. Example: ?ids=1001&ids=1002
- `created_at_min` string

  Retrieve customers created after this date. It's in UTC (0 timezone), formatted as ISO-8601
- `created_at_max` string

  Retrieve customers created before this date. It's in UTC (0 timezone), formatted as ISO-8601
- `updated_at_min` string

  Retrieve customers last updated after this date. It's in UTC (0 timezone), formatted as ISO-8601
- `updated_at_max` string

  Retrieve customers last updated before this date. It's in UTC (0 timezone), formatted as ISO-8601
- `email` string

  Filter customers by email
- `contact` string

  Filter customers by contact information (email or phone)

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `customers` object[]

    List of customers

    *   Array \[

    - `id` string

      Customer ID
    - `email` string

      Customer's email address
    - `created_at` string

      Timestamp when the customer was created, in ISO8601 format
    - `updated_at` string

      Timestamp when the customer was last updated, in ISO8601 format
    - `first_name` string

      Customer's first name
    - `last_name` string

      Customer's last name
    - `phone` string

      Customer's phone number
    - `tags` string[]

      Tags associated with the customer
    - `name` string

      Full name of the customer
    - `phone_area_code` string

      Area code of the phone number
    - `contact_type` string

      Contact type, either email or phone
    - `sms_subscribed_flag` int32

      Customer's SMS subscription status flag
    - `addresses` object[]

      List of all customer addresses

      *   Array \[

      - `id` string

        Address ID
      - `customer_id` string

        ID of the customer this address belongs to
      - `first_name` string

        First name of the consignee
      - `last_name` string

        Last name of the consignee
      - `company` string

        Company name
      - `city` string

        City of the address
      - `province` string

        Province or state of the address
      - `country` string

        Country name of the address
      - `zip` string

        Postal or ZIP code
      - `province_code` string

        Province code
      - `country_code` string

        ISO country code
      - `gender` string

        Gender of the consignee
      - `phone` string

        Phone number associated with the address
      - `phone_area_code` string

        Area code of the phone number
      - `area` string

        Area or region of the address
      - `email` string

        Email associated with the address
      - `name` string

        Full name of the consignee
      - `address1` string

        Primary street address
      - `address2` string

        Secondary street address
      - `country_name` string

        Full name of the country
      - `default` boolean

        Indicates if this is the default address
      *   \]
    - `accepts_marketing` boolean

      Indicates if the customer is subscribed to marketing emails
    - `source` string

      Source of the customer data
    - `free_tax` boolean

      Indicates if the customer is exempt from taxes
    - `registered` boolean

      Indicates if the customer is registered
    - `orders_count` int32

      Number of orders placed by the customer
    - `first_order_at` string

      First order timestamp
    - `last_order_at` string

      Timestamp of the customer's last order
    - `total_spent` string

      Total amount spent by the customer
    - `subscribed_flag` int32

      Customer's marketing subscription status flag
    - `accepts_sms_marketing` boolean

      Indicates if the customer is subscribed to SMS marketing campaigns
    *   \]
  - `cursor` string

    The cursor for the next page of results
  - `has_more` boolean

    Whether there are more records

```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
  }
}
```