Search customers

get https://app.ecwid.com/api/v3/{storeId}/customers

Search customers by a keyword or basic filters: number of orders made, name, email, customer group and more.

Headers

Name	Type	Description
Authorization	string	oAuth token with mandatory `Bearer` before it. Example: `Bearer e*s0`, where `e*s0` should be replaced with your oAuth token.

Q: How can I specify what fields I want to receive in response?

Add responseFields query param, specifying field names you want to receive.
Example: ?responseFields=items(id,email,taxId)

All query params

Name	Type	Description
keyword	string	Customer search term. Used to search in customer name and email only. If your keywords contain special characters, it may make sense to URL encode them before making a request
name	string	Customer name
email	string	Customer email
customerGroup	number	Customer group ID
customerGroupIds	string	Filter customers by several group IDs (e.g.`/customers?customerGroupIds=0,1,2`)
minOrderCount	number	Minimum number of orders a customer placed
maxOrderCount	number	Maximum number of orders a customer placed
minSalesValue	number	Min total that customers spent in a store
maxSalesValue	number	Max total that customers spent in a store
purchasedProductIds	string	Filter customers by purchased product IDs (e.g.`customers?purchasedProductIds=1243,5345,2424`)
acceptMarketing	boolean	`true` if customer has accepted email marketing. `false` otherwise
b2b_b2c	string	Order type: business-to-business (`b2b`) or business-to-consumer (`b2c`)
fiscalCode	string	Fiscale code of a customer
electronicInvoicePecEmail	string	PEC email for invoices
electronicInvoiceSdiCode	string	SDI code for invoices
createdFrom	string	Customer register date/time (lower bound). Supported formats: UNIX timestamp Examples: `1447804800`
createdTo	string	Customer register date/time (upper bound). Supported formats: UNIX timestamp
updatedFrom	string	Customer last update date/time (lower bound). Supported formats: UNIX timestamp
updatedTo	string	Customer last update date/time (upper bound). Supported formats: UNIX timestamp
sortBy	string	Sort order. Supported values: `NAME_ASC` default `NAME_DESC` `EMAIL_ASC` `EMAIL_DESC` `ORDER_COUNT_ASC` `ORDER_COUNT_DESC` `REGISTERED_DATE_DESC` `REGISTERED_DATE_ASC` `UPDATED_DATE_DESC` `UPDATED_DATE_ASC` `SALES_VALUE_ASC` `SALES_VALUE_DESC` `FIRST_ORDER_DATE_ASC` `FIRST_ORDER_DATE_DESC` `LAST_ORDER_DATE_ASC` `LAST_ORDER_DATE_DESC`
offset	number	Offset from the beginning of the returned items list (for paging)
limit	number	Maximum number of returned items. Maximum allowed value: `100`. Default value: `10`
taxExempt	boolean	Use `true` to search only for tax-exempt customers and `false` for the ones without tax exemption.
countryCodes	string	Country code (2-letter code)

Q: How to find customer emails I can use for promotions?

Use the acceptMarketing filter when searching for orders / customers or when getting order / customer details. If it is set to true or null, you can use their email for promotions in your app or customization. If it's set to false – you cannot send promotional emails to that person.

Q: Some customers don't have billing and shipping info. Why?

Ecwid saves data for registered customers only.

If a customer placed order without registration, it counts as a guest checkout. However, a basic account is created for them with no address information saved. If a customer has registered before, they will have a billing and/or shipping address specified in their account.

Response

A JSON object of type 'CustomerSearchResult' with the following fields:

CustomerSearchResult

Field	Type	Description
total	number	The total number of found items (might be more than the number of returned items)
count	number	The number of returned items
offset	number	Offset from the beginning of the returned items list (for paging)
limit	number	Maximum number of returned items. Maximum allowed value: `100`. Default value: `10`
items	Array	The items list

CustomerSearchEntry

Field	Type	Description
id	number	Unique internal customer ID
email	string	Customer email
name	string	Customer full name
totalOrderCount	number	Number of customer's orders
registered	string	Registration date, e.g `2014-06-06 18:57:19 +0400`
updated	string	Last updated date, e.g `2014-06-06 18:57:19 +0400`
billingPerson	Person	Customer's billing name/address
shippingAddresses	Array<ShippingAddress>	Customer address book items (deprecated for new instant site customer accounts)
contacts	Array<Contacts>	Customer's contact information
customerGroupId	number	Customer group ID
customerGroupName	string	Customer group name
taxId	string	Customer tax ID
taxIdValid	boolean	`true` if customer tax ID is valid, `false` otherwise
taxExempt	boolean	`true` if customer is tax exempt, `false` otherwise. Learn more
acceptMarketing	boolean	`true` if customer has accepted email marketing and you can use their email for promotions. If value is `false`, you can't use this email for promotions
lang	string	Customer's language code (based on the language of the storefront).
stats	<Stats>	Customer's statistical information

Person

Field	Type	Description
name	string	Customer full name
companyName	string	Customer company name
street	string	Street
city	string	City
countryCode	string	Country code (2-letter code)
countryName	string	Country name
postalCode	string	Postal code (zip code)
stateOrProvinceCode	string	State/province code
stateOrProvinceName	string	State/province name
phone	string	Phone number

ShippingAddress

Field	Type	Description
id	number	Internal address ID
name	string	Customer full name
companyName	string	Customer company name
street	string	Street
city	string	City
countryCode	string	Country (2-digits code)
countryName	string	Country name
postalCode	string	Postal code (zip code)
stateOrProvinceCode	string	State/province code
stateOrProvinceName	string	State/province name
phone	string	Phone number

Contacts

Field	Type	Description
id	number	Unique contact Id
contact	string	Customer's contact data (email, phone, etc)
type	string	Type of contact data. Values: `EMAIL`, `PHONE`, `WHATSAPP`, `TELEGRAM`, `VIBER`, `FACEBOOK`, `INSTAGRAM`, `TWITTER`, `TIKTOK`, `URL`, `OTHER`
default	boolean	`true` if the contact is primary (default). Only one contact of each type (`EMAIL`, `PHONE`) can be default.
note	string	Merchant's comments about a contact
orderBy	number	Sort position
timestamp	string	Date of creating/updating the contact

Stats

Field	Type	Description
numberOfOrders	number	Number of customer orders in the store
salesValue	number	Total revenue received from the customer
averageOrderValue	number	Average revenue received from the customer
firstOrderDate	string	Date the customer placed the first order in the store
lastOrderDate	string	Date the customer placed the latest order in the store

Errors

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP Status	Meaning
400	Request parameters are malformed
415	Unsupported content-type: expected `application/json` or `text/json`
500	Cannot retrieve the customers info because of an error on the server

Error response body (optional)

Field	Type	Description
errorMessage	string	Error message