---
updatedAt: 2026-03-23T22:37:13.000Z
---

# Customers

# Customers

## What is a Customer in ecartAPI?

A **Customer** is a buyer profile on a connected store. It represents the person who makes purchases — their name, email, phone, and addresses. Customers are typically created when they place their first order, though many platforms also allow creating customer records independently.

Every ecommerce platform has its own way of representing customers — some have dedicated "Customer" resources, others base them on WordPress users, tie buyer data to the order, or expose only limited buyer info. ecartAPI normalizes all of these into a single canonical shape.

### The canonical model

ecartAPI's canonical customer includes:

* A unique identifier.
* Personal info: first name, last name, email, phone.
* One or more addresses (billing and shipping).
* Notes added by the store owner.
* A status (active/disabled).
* Order history accessible via the customer id.
* Dates: when the customer record was created and last updated.

All platforms are normalized to this model. Some platforms have limited customer data (e.g., minimal buyer info on marketplaces), while others are richer (e.g., extensive CRM fields). The **core shape is always the same**.

> **Important:** Customer resource availability varies significantly across platforms. Not all platforms support full CRUD operations, and some (like Amazon) provide very limited customer data.

***

## API endpoints

| Method | Path                            | Description                                              |
| ------ | ------------------------------- | -------------------------------------------------------- |
| GET    | `/api/v2/customers`             | List customers with filters.                             |
| GET    | `/api/v2/customers/count`       | Count customers matching filters. Platform-dependent.    |
| GET    | `/api/v2/customers/{id}`        | Get a single customer by id.                             |
| POST   | `/api/v2/customers`             | Create a customer. Not available on all platforms.       |
| PUT    | `/api/v2/customers/{id}`        | Update a customer. Not available on all platforms.       |
| DELETE | `/api/v2/customers/{id}`        | Delete a customer. Not available on all platforms.       |
| GET    | `/api/v2/customers/{id}/orders` | List orders for a specific customer. Platform-dependent. |

> **Note:** The `{id}` parameter is the customer's identifier **on the connected platform**. ecartAPI does not generate its own ids for customers.

***

## Query filters

When listing customers, you can pass query parameters to filter, paginate, and sort results.

| Parameter                          | Description                                                       |
| ---------------------------------- | ----------------------------------------------------------------- |
| `ids`                              | Comma-separated list of customer ids to retrieve.                 |
| `limit`                            | Maximum number of customers per page.                             |
| `page`                             | Page token or page number for pagination.                         |
| `sinceId`                          | Return customers created after this id (cursor-based pagination). |
| `createdAt[from]`, `createdAt[to]` | Filter by creation date range. ISO 8601 strings recommended.      |
| `updatedAt[from]`, `updatedAt[to]` | Filter by last-updated date range.                                |
| `name`                             | Filter by customer name.                                          |
| `search`                           | Free-text search across customer fields.                          |
| `email`                            | Filter by email address.                                          |

> **Important:** Not every filter works on every platform. The most universally supported filters are `limit` and `page`. Filters like `email`, `name`, and `search` depend on platform capabilities.

***

## Response shape

Every customer response follows the same canonical shape.

### Root fields

| Field       | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| `id`        | string | The customer's unique identifier on the platform.    |
| `email`     | string | Customer's email address.                            |
| `firstName` | string | Customer's first name.                               |
| `lastName`  | string | Customer's last name.                                |
| `phone`     | string | Customer's phone number.                             |
| `currency`  | string | Preferred currency code.                             |
| `note`      | string | Notes about the customer (added by the store owner). |
| `addresses` | array  | Array of address objects (see below).                |

### Nested objects

#### `status`

| Field    | Type   | Description                          |
| -------- | ------ | ------------------------------------ |
| `id`     | string | Platform-specific status identifier. |
| `status` | string | Platform-native status value.        |

#### `dates`

| Field       | Type   | Description                      |
| ----------- | ------ | -------------------------------- |
| `createdAt` | string | ISO 8601 creation timestamp.     |
| `updatedAt` | string | ISO 8601 last-updated timestamp. |

#### `addresses` (array items)

Each address in the `addresses` array follows this shape:

| Field             | Type    | Description                                   |
| ----------------- | ------- | --------------------------------------------- |
| `id`              | string  | Address identifier.                           |
| `firstName`       | string  | Recipient first name.                         |
| `lastName`        | string  | Recipient last name.                          |
| `address1`        | string  | Primary address line (street, number).        |
| `address2`        | string  | Secondary address line (apartment, suite).    |
| `city`            | string  | City name.                                    |
| `postalCode`      | string  | Postal/ZIP code.                              |
| `phone`           | string  | Phone number for this address.                |
| `company`         | string  | Company name, if applicable.                  |
| `references`      | string  | Address references or delivery instructions.  |
| `defaultBilling`  | boolean | Whether this is the default billing address.  |
| `defaultShipping` | boolean | Whether this is the default shipping address. |

#### `addresses.country` / `addresses.state`

| Field      | Type   | Description                             |
| ---------- | ------ | --------------------------------------- |
| `code`     | string | Country/state code.                     |
| `name`     | string | Country/state full name.                |
| `codeIso2` | string | ISO 3166-1 alpha-2 code (country only). |
| `codeIso3` | string | ISO 3166-1 alpha-3 code (country only). |

***

## Important notes

* **Availability varies significantly.** Some platforms have rich customer APIs (Shopify, BigCommerce, WooCommerce), while others provide very limited customer data (Amazon, some marketplaces).
* **Count is not universal.** The `/count` endpoint is only available on platforms that implement it (e.g., Shopify, BigCommerce, Jumpseller).
* **Customer orders** (`/customers/{id}/orders`) availability is platform-dependent. It is supported on platforms like Shopify and Bling.
* **Create requires `firstName` and `lastName`.** These are the only required fields when creating a customer.
* **Response fields are platform-dependent.** Not all fields listed in the response shape are available for every ecommerce platform. Some properties may be absent or returned as `null` depending on what the connected platform's API provides.
* If a platform does not support an operation, ecartAPI returns `400` with `"The resource is not available for this ecommerce"`.