Search customers

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

Request and response example

Request:

GET /api/v3/1003/customers HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com

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": "Ecwid test acc",
      "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",
      "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
}

Required access scopes

Your app must have the following access scopes to make this request: read_customers

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Name	Type	Description
keyword	string	Search term for both customer name and email. Special characters must be URI-encoded.
name	string	Search term for customer's name – billingPerson.name field.
email	string	Search term for customer's email.
phone	string	Search term for customer's phone number or its part in both shippingAddress and contacts. Checks all saved addresses and contacts.
city	string	Search term for customer's city in shippingAddress. Checks all saved addresses.
postalCode	string	Search term for customer's ZIP code in shippingAddress. Checks all saved addresses.
stateOrProvinceCode	string	Search term for customer's two-digit state code in shippingAddress. Checks all saved addresses.
countryCodes	string	Search term for customer's country codes in shippingAddress. Checks all saved addresses.
companyName	string	Search term for customer's company name in shippingAddress. Checks all saved addresses.
acceptMarketing	boolean	Set true to only find customers who accepted receiving marketing emails. Set false to only find customers who rejected such emails. Do not add param to the request to receive both.
lang	string	Search term for customer's languages used for making orders.
customerGroupIds	string	Search term for customer group ID. Supports multiple values, for example, 123456,234567.
minOrderCount	number	Search by the minimum number of customer's orders.
maxOrderCount	number	Search by the maximum number of customer's orders.
minSalesValue	number	Search by the minimum total order value of customer's orders.
maxSalesValue	number	Search by the maximum total order value of customer's orders.
purchasedProductIds	string	Search term for product IDs in customer's orders.
b2b_b2c	string	Defines business-to-customer relation. One of: b2c - Business-to-customer (default) b2b - Business-to-business
taxExempt	boolean	Set true to only find tax-exempt customers. Set false to only find customers without tax exemption. Do not add param to the request to receive both.
createdFrom	number/string	Datetime when a customer registered in the store or placed their first order without registration (lower bound). Supported formats: UNIX timestamp, datetime. Examples: 1447804800, 2023-01-15 19:27:50
createdTo	number/string	Datetime when a customer registered in the store or placed their first order without registration (upper bound). Supported formats: UNIX timestamp, datetime. Examples: 1447804800, 2023-01-15 19:27:50
updatedFrom	number/string	Datetime of the latest update of customer's details (lower bound. Supported formats: UNIX timestamp, datetime. Examples: 1447804800, 2023-01-15 19:27:50
updatedTo	number/string	Datetime of the latest update of customer's details (upper bound. Supported formats: UNIX timestamp, datetime. Examples: 1447804800, 2023-01-15 19:27:50
sortBy	string	Sorting order for the results. One of: 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	Offset from the beginning of the returned items list. Used when the response contains more items than limit allows to receive in one request. Usually used to receive all items in several requests with multiple of a hundred, for example: ?offset=0 for the first request, ?offset=100, for the second request, ?offset=200, for the third request, etc.
limit	number	Limit to the number of returned items. Maximum and default value (if not specified) is 100.
responseFields	string	Specify the exact fields to receive in response JSON. If not specified, the response JSON will have all available fields for the entity. Example: ?responseFields=total,items(id,name,email)

Example of using responseFields param:

Request

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

Response

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

Headers

The Authorization header is required.

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

Response JSON

A JSON object with the following fields:

Field	Type	Description
total	number	Total number of found items (might be more than the number of returned items).
count	number	Total number of items returned in the response.
offset	number	Offset from the beginning of the returned items list specified in the request.
limit	number	Maximum number of returned items specified in the request. Maximum and default value: 100.
items	array of objects items	Detailed information about returned customers.
allCustomerCount	number	Total count of unique customers in the store.

items

Field	Type	Description
id	number	Unique internal customer ID.
email	string	Customer's email.
name	string	Customer's name. Duplicates billingPerson.name field.
totalOrderCount	number	Total count of orders placed by the customer.
registered	string	Customer's registration datetime, for example, 2014-06-06 18:57:19 +0400
updated	string	Datetime of the latest update of customer's details, for example, 2014-06-06 18:57:19 +0400
billingPerson	object billingPerson	Customer's billing name/address.
shippingAddresses	array of objects shippingAddresses	List of saved shipping addresses for the customer.
contacts	array of objects contacts	Customer's contact information: email, phone, social media links.
customerGroupName	string	Name of the customer group the customer is assigned to.
customerGroupId	number	ID of the customer group the customer is assigned to.
taxId	string	Customer's tax ID.
taxIdValid	boolean	Defines if customer's tax ID is valid.
taxExempt	boolean	Defines if customer is tax exempt. Requires a valid tax ID. Read more about handling tax exempt customers in Help Center.
acceptMarketing	boolean	Defines if the customer has accepted email marketing. If true, you can use customer's email for promotions.
lang	string	Customer's language code. Customers see storefront and emails in this language. This language must be one of the translations enabled in the store.
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 of objects favorites	List of customer's favorite products.

billingPerson

Field	Type	Description
name	string	Full name of the customer.
firstName	string	First name of the customer. Only shows when the name field has at least two words.
lastName	string	Last name of the customer. Only shows when the name field has at least two words.
companyName	string	Customer's company name.
street	string	Address line 1 and address line 2, separated by \n.
city	string	City.
countryCode	string	Two-letter country code.
countryName	string	Country name.
postalCode	string	Postal/ZIP code.
stateOrProvinceCode	string	State/province code, for example, NY.
stateOrProvinceName	string	State/province name.
phone	string	Customer's phone number.

shippingAddresses

Field	Type	Description
id	number	Internal ID of the saved address.
name	string	Full name of the customer.
companyName	string	Customer's company name.
street	string	Address line 1 and address line 2, separated by \n.
city	string	City.
countryCode	string	Two-letter country code.
countryName	string	Country name.
postalCode	string	Postal/ZIP code.
stateOrProvinceCode	string	State/province code, for example, NY.
stateOrProvinceName	string	State/province name.
phone	string	Customer's phone number.
addressFormatted	string	Formatted full address. Includes street, city, state, and country names.

contacts

Field	Type	Description
contact	string	Email or link to reach the contact. Examples: [email protected] contact for EMAIL type. https://www.facebook.com/myshop_page contact for FACEBOOK type. Required
handle	string	Contact identifier on social media. For example, for FACEBOOK type of contact, it's a page slug: contact field: https://www.facebook.com/myshop_page handle field: myshop_page
note	string	Store owner's notes on the contact.
type	string	Contact type. Customer can have several contacts of the same type. One of: EMAIL, PHONE, FACEBOOK, INSTAGRAM, TWITTER, YOUTUBE, TIKTOK, PINTEREST, VK, FB_MESSENGER, WHATSAPP, TELEGRAM, VIBER, URL, OTHER. Required
default	boolean	Defines if it's a default customer contact. Only one contact of the same type can be default.
orderBy	boolean	Sorting order for contacts on the customer details page. Starts with 0 and increments by 1.
timestamp	string	Datetime when the customer contact was created.

stats

Field	Type	Description
numberOfOrders	number	Count of customer's orders in the store.
salesValue	number	Total cost of orders placed by the customer.
averageOrderValue	number	Average total of orders placed by the customer.
firstOrderDate	string	Date the customer placed their first order.
lastOrderDate	string	Date the customer placed their last order.

favorites

Field	Type	Description
productId	number	Internal ID of the favorited product, for example, 689454040
addedTimestamp	string	Datetime when the product was added to favorites, favorites 2024-09-11 06:43:02 +0000