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".