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.

Request and response example

Request:

curl --location 'https://app.ecwid.com/api/v3/1003/customers' \
--header 'Authorization: Bearer secret_ab***cd'

Response:

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 177737165,
            "name": "Support team",
            "email": "[email protected]",
            "registered": "2021-12-21 06:05:58 +0000",
            "updated": "2024-06-04 21:15:10 +0000",
            "totalOrderCount": 0,
            "customerGroupId": 0,
            "customerGroupName": "General",
            "billingPerson": {
                "name": "Support team",
                "firstName": "Support",
                "lastName": "team"
            },
            "shippingAddresses": [],
            "contacts": [
                {
                    "id": 113861381,
                    "contact": "[email protected]",
                    "type": "EMAIL",
                    "default": true,
                    "orderBy": 0,
                    "timestamp": "2024-06-04 21:15:10 +0000"
                }
            ],
            "taxExempt": false,
            "taxId": "",
            "taxIdValid": true,
            "b2b_b2c": "b2c",
            "fiscalCode": "",
            "electronicInvoicePecEmail": "",
            "electronicInvoiceSdiCode": "",
            "acceptMarketing": false,
            "stats": {
                "numberOfOrders": 0,
                "salesValue": 0,
                "averageOrderValue": 0
            },
            "privateAdminNotes": "",
            "favorites": []
        },
        {
            "id": 277137633,
            "name": "test",
            "email": "[email protected]",
            "registered": "2024-08-21 07:52:09 +0000",
            "updated": "2024-08-21 07:52:09 +0000",
            "totalOrderCount": 0,
            "customerGroupId": 0,
            "customerGroupName": "General",
            "billingPerson": {
                "name": "test"
            },
            "shippingAddresses": [
                {
                    "id": 193416515,
                    "name": "test",
                    "companyName": "test",
                    "street": "test",
                    "city": "test",
                    "countryCode": "GE",
                    "countryName": "Georgia",
                    "stateOrProvinceCode": "TB",
                    "stateOrProvinceName": "Tbilisi",
                    "phone": "00000000000",
                    "createdDate": "2024-08-21 07:52:09 +0000",
                    "defaultAddress": true,
                    "orderBy": 0,
                    "addressFormatted": "test, test, test Tbilisi, Georgia"
                }
            ],
            "contacts": [
                {
                    "id": 176135453,
                    "contact": "00000000000",
                    "type": "PHONE",
                    "default": true,
                    "orderBy": 0,
                    "timestamp": "2024-08-21 07:52:09 +0000"
                },
                {
                    "id": 176135452,
                    "contact": "[email protected]",
                    "type": "EMAIL",
                    "default": true,
                    "orderBy": 0,
                    "timestamp": "2024-08-21 07:52:09 +0000"
                }
            ],
            "taxExempt": false,
            "taxId": "",
            "taxIdValid": true,
            "b2b_b2c": "b2c",
            "fiscalCode": "",
            "electronicInvoicePecEmail": "",
            "electronicInvoiceSdiCode": "",
            "lang": "en",
            "stats": {
                "numberOfOrders": 1,
                "salesValue": 97,
                "averageOrderValue": 97,
                "firstOrderDate": "2024-08-21 07:52:09 +0000",
                "lastOrderDate": "2024-08-21 07:52:09 +0000"
            },
            "privateAdminNotes": "",
            "favorites": []
        }
    ],
    "allCustomerCount": 2
}

Access scopes

Requires the following access scope: read_customers

Path params

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Param	Type	Description
name	string	Search term for customer name.
email	string	Search term for customer email address.
keyword	string	Search term for both customer name and email. Special characters must be URI-encoded.
customerGroup	number	Search by a single customer group ID, e.g. `123456`.
customerGroupIds	number	Search by multiple customer group IDs, e.g. `123456,234567`.
minOrderCount	number	Search term for the minimum number of orders placed by customers.
maxOrderCount	number	Search term for the maximum number of orders placed by customers.
minSalesValue	number	Search term for the minimum total order value from orders placed by a customer.
maxSalesValue	number	Search term for the maximum total order value from orders placed by a customer.
purchasedProductIds	number	Search by product IDs in orders placed by a customer.
countryCodes	string	Set a list of country codes to find customers. Find available values in Dictionaries.
acceptMarketing	boolean	Set `true` to search customers who accepted receiving marketing emails. Set `false` to find customers who rejected such emails.
b2b_b2c	string	Order type: business-to-business (`b2b`) or business-to-consumer (`b2c`)
electronicInvoicePecEmail	string	Search term for invoice PEC email.
electronicInvoiceSdiCode	string	Search term for invoice SDI code.
fiscalCode	string	Customer's Fiscale Code (only for Italy).
taxExempt	boolean	Set `true` to search only for tax-exempt customers. Set `false` to search customers without tax exemption.
createdFrom	string	Customer creation date/time (lower bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`
createdTo	string	Customer creation date/time (upper bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`
updatedFrom	string	Customer update date/time (lower bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`
updatedTo	string	Customer update date/time (upper bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`
sortBy	string	Sort order. Supported values: `NAME_ASC`, `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
limit	number	Maximum number of returned items. Maximum and default value is `100`.
responseFields	string	Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body. Example: `?responseFields=total,items(id,name,email)`

Example of using responseFields param:

curl --location 'https://app.ecwid.com/api/v3/1003/customers?responseFields=total,items(id,name,email)' \
--header 'Authorization: Bearer secret_ab***cd'

{
    "total": 2,
    "items": [
        {
            "id": 177737165,
            "name": "Support team",
            "email": "[email protected]"
        },
        {
            "id": 277137633,
            "name": "TEST",
            "email": "[email protected]"
        }
    ]
}

Headers

The Authorization header with a secret access token is required.

Header	Format	Description
Authorization	`Bearer secret_ab***cd`	Access token of the application.

Response

A JSON object with the following fields:

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: `100`
items	Array items	Detailed information about found customers.
allCustomerCount	number	Total count of unique customers in the store.

items

Field	Type	Description
id	number	Unique internal customer ID.
email	string	Customer email.
name	string	Customer full name.
totalOrderCount	number	Count 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	Object billingPerson	Customer's billing name/address
shippingAddresses	Array shippingAddresses	List of saved shipping addresses for the customer.
contacts	Array contacts	Customer's contact information: email, phone, social media links.
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	Object stats	Customer's sales stats: number of orders, total revenue, first order date, etc.
privateAdminNotes	string	Personal notes about the customer. Visible only to the store owner.
favorites	Array favorites	List of customer's favorite products.

billingPerson

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

shippingAddresses

Array of objects, where each object contains the following fields:

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
addressFormatted	string	Formatted full address. Includes street, city, state, and country names.

contacts

Array of objects, where each object contains the following fields:

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

favorites

Field	Type	Description
productId	number	ID of the favorited product, e.g. `689454040`
addedTimestamp	string	Datetime when the product was added to favorites, e.g. `"2024-09-11 06:43:02 +0000"`