Search customers

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

Headers

NameTypeDescription
AuthorizationstringoAuth 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

NameTypeDescription
keywordstringCustomer 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
namestringCustomer name
emailstringCustomer email
customerGroupnumberCustomer group ID
customerGroupIdsstringFilter customers by several group IDs (e.g./customers?customerGroupIds=0,1,2)
minOrderCountnumberMinimum number of orders a customer placed
maxOrderCountnumberMaximum number of orders a customer placed
minSalesValuenumberMin total that customers spent in a store
maxSalesValuenumberMax total that customers spent in a store
purchasedProductIdsstringFilter customers by purchased product IDs (e.g.customers?purchasedProductIds=1243,5345,2424)
acceptMarketingbooleantrue if customer has accepted email marketing. false otherwise
b2b_b2cstringOrder type: business-to-business (b2b) or business-to-consumer (b2c)
fiscalCodestringFiscale code of a customer
electronicInvoicePecEmailstringPEC email for invoices
electronicInvoiceSdiCodestringSDI code for invoices
createdFromstringCustomer register date/time (lower bound). Supported formats:
  • UNIX timestamp
Examples:
  • 1447804800
createdTostringCustomer register date/time (upper bound). Supported formats:
  • UNIX timestamp
updatedFromstringCustomer last update date/time (lower bound). Supported formats:
  • UNIX timestamp
updatedTostringCustomer last update date/time (upper bound). Supported formats:
  • UNIX timestamp
sortBystringSort 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
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
taxExemptbooleanUse true to search only for tax-exempt customers and false for the ones without tax exemption.
countryCodesstringCountry 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

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe number of returned items
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArrayThe items list

CustomerSearchEntry

FieldTypeDescription
idnumberUnique internal customer ID
emailstringCustomer email
namestringCustomer full name
totalOrderCountnumberNumber of customer's orders
registeredstringRegistration date, e.g 2014-06-06 18:57:19 +0400
updatedstringLast updated date, e.g 2014-06-06 18:57:19 +0400
billingPersonPersonCustomer's billing name/address
shippingAddressesArray<ShippingAddress>Customer address book items (deprecated for new instant site customer accounts)
contactsArray<Contacts>Customer's contact information
customerGroupIdnumberCustomer group ID
customerGroupNamestringCustomer group name
taxIdstringCustomer tax ID
taxIdValidbooleantrue if customer tax ID is valid, false otherwise
taxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more
acceptMarketingbooleantrue 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
langstringCustomer's language code (based on the language of the storefront).
stats<Stats>Customer's statistical information

Person

FieldTypeDescription
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry code (2-letter code)
countryNamestringCountry name
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
stateOrProvinceNamestringState/province name
phonestringPhone number

ShippingAddress

FieldTypeDescription
idnumberInternal address ID
namestringCustomer full name
companyNamestringCustomer company name
streetstringStreet
citystringCity
countryCodestringCountry (2-digits code)
countryNamestringCountry name
postalCodestringPostal code (zip code)
stateOrProvinceCodestringState/province code
stateOrProvinceNamestringState/province name
phonestringPhone number

Contacts

FieldTypeDescription
idnumberUnique contact Id
contactstringCustomer's contact data (email, phone, etc)
typestringType of contact data. Values: EMAIL, PHONE, WHATSAPP, TELEGRAM, VIBER, FACEBOOK, INSTAGRAM, TWITTER, TIKTOK, URL, OTHER
defaultbooleantrue if the contact is primary (default). Only one contact of each type (EMAIL, PHONE) can be default.
notestringMerchant's comments about a contact
orderBynumberSort position
timestampstringDate of creating/updating the contact

Stats

FieldTypeDescription
numberOfOrdersnumberNumber of customer orders in the store
salesValuenumberTotal revenue received from the customer
averageOrderValuenumberAverage revenue received from the customer
firstOrderDatestringDate the customer placed the first order in the store
lastOrderDatestringDate 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 StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the customers info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
Language
Authorization
Query