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.
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
minOrderCount
number
Minimum number of order a customer placed
maxOrderCount
number
Maximum number of order a customer placed
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)
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_ASCdefault
NAME_DESC
EMAIL_ASC
EMAIL_DESC
ORDER_COUNT_ASC
ORDER_COUNT_DESC
REGISTERED_DATE_DESC
REGISTERED_DATE_ASC
UPDATED_DATE_DESC
UPDATED_DATE_ASC
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
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
