LogoLogo
Build appsContact API support
  • Build apps
  • Site Templates
  • API Reference
  • Changelog
  • REST API
    • REST API overview
    • Store Profile
      • Get store profile
      • Update store profile
      • Upload store logo image
      • Delete store logo image
      • Store reports
        • Get store reports
        • Get latest store update stats
        • Get deleted items history
    • Orders
      • Search orders
      • Get order
      • Get last order
      • Calculate order details
      • Update order
      • Create order
      • Delete order
      • Get repeat order URL
      • Order invoices
        • Get order receipt PDF
        • Get tax invoices for order
        • Generate tax invoice for order
      • Order statuses
        • Search order statuses
        • Get order status
        • Update custom order status
      • Order extra fields
        • Search order extra fields
        • Update order extra field
        • Add extra fields to order
        • Delete order extra field
      • Abandonned carts
        • Search abandoned carts
        • Get abandoned cart
        • Update abandoned cart
        • Convert abandoned cart to order
      • Recurring subscriptions
        • Search recurring subscriptions
        • Get recurring subscription
        • Update recurring subscription
    • Products
      • Search products
      • Get product
      • Update product
      • Create product
      • Delete product
      • Delete all products
      • Adjust product stock
      • Get product filters
      • Get recently used product swatches
      • Search product brands
      • Product images and videos
        • Upload main product image
        • Upload main product image (async)
        • Upload gallery product image
        • Upload gallery product image (async)
        • Delete main product image
        • Delete gallery product image
        • Delete all gallery product images
        • Upload main product video
        • Upload gallery product video
        • Upload cover for gallery video
        • Delete main product video
        • Delete gallery product video
        • Download gallery product video
        • Bulk update product images and videos
      • Product files
        • Upload product file
        • Download product file
        • Delete product file
        • Delete all product files
        • Change product file description
      • Product variations
        • Search product variations
        • Get product variation
        • Update product variation
        • Create product variation
        • Delete product variation
        • Delete all product variations
        • Adjust product variation stock
        • Upload product variation image
        • Upload product variation image (async)
        • Delete product variation image
      • Product types and attributes
        • Search product types
        • Get product type
        • Update product type and attributes
        • Create product type
        • Delete product type
      • Product reviews
        • Search product reviews
        • Get product reviews stats
        • Update product review status
        • Bulk update/delete product reviews
        • Delete product review
    • Categories
      • Search categories
      • Search categories by path
      • Get category
      • Update category
      • Create category
      • Delete category
      • Category images
        • Upload category image
        • Upload category image (async)
        • Delete category image
      • Manage order of categories in the store
        • Get order of categories
        • Update order of categories
      • Manage order of products in the category
        • Get order of products
        • Update order of products
        • Assign products to the category
        • Unassign products from the category
    • Customers
      • Search customers
      • Get customer
      • Update customer
      • Create customer
      • Delete customer
      • Customer groups
        • Search customer groups
        • Get customer group
        • Update customer group name
        • Create customer group
        • Delete customer group
      • Customer contacts
        • Search customer contacts
        • Get customer contact
        • Update customer contact
        • Create customer contact
        • Delete customer contact
      • Customer extra fields
        • Search customer extra fields
        • Get customer extra field
        • Update customer extra field
        • Create customer extra field
        • Delete customer extra field
    • Discounts
      • Promotions
        • Search promotions
        • Update promotion
        • Create promotion
        • Delete promotion
      • Discount coupons
        • Search discount coupons
        • Get discount coupon
        • Update discount coupon
        • Create discount coupon
        • Delete discount coupon
    • Domains
      • Search store domains
      • Update store domains
      • Search domains for purchase
      • Purchase domain
      • Send domain verification email
      • Reset domain password
    • Dictionaries
      • Country codes
      • Currency codes
      • Currency codes by country
      • State codes by country
      • Tax classes by country
    • Staff accounts
      • Search staff accounts
      • Get staff account
      • Get staff account scopes
      • Update staff account
      • Create staff account
      • Delete staff account
      • Resend staff account invite
      • Cancel staff account invite
    • Application
      • Get app subscription status
      • Cancel app subscription
      • Get all app storage data
      • Get specific app storage data
      • Update specific app storage data
      • Delete specific app storage data
      • Add app storage data
      • Custom charge with Ecwid billing
    • Batch requests
      • Create batch request
      • Get batch status
      • Search batch requests by status
      • Stop batch request
      • Stop and delete batch request
    • Shipping options
      • Search shipping options
      • Update shipping option
      • Create shipping option
      • Delete shipping option
    • Payment options
      • Search payment options
      • Get payment option
      • Update payment option
      • Create payment option
      • Delete payment option
    • Checkout extra fields
      • Add checkout extra fields with JavaScript
      • Manage checkout extra fields with REST API
        • Search checkout extra fields
        • Get checkout extra field
        • Update checkout extra field
        • Create checkout extra field
        • Delete checkout extra field
    • Storefront widget details
      • Get page slug and static code
      • Set base URL for storefront widgets
      • Optimize custom website SEO with better URLs
        • Enable Clean Store URLs on a custom website
        • Set Custom Page Slugs on a custom website
      • Dynamic loading for storefront widget
      • SSO (Single-Sign-On) for websites
        • Add SSO to the website
        • Customize SSO on the website
        • SSO code examples
      • Static store pages
        • Static code for home page
        • Static code for category page
        • Static code for product page

Lightspeed® 2025

On this page
  • Required access scopes
  • Path params
  • Query params
  • Headers
  • Response JSON

Was this helpful?

  1. REST API
  2. Customers

Search customers

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

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": "ec.apps@lightspeedhq.com",
            "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": "ec.apps@lightspeedhq.com",
                    "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": "ecwid.test@ecwid-test.com",
            "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": "ecwid.test@ecwid-test.com",
                    "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.

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.

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:

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": "ec.apps@lightspeedhq.com"
        },
        {
            "id": 277137633,
            "name": "Ecwid test acc",
            "email": "ecwid.test@ecwid-test.com"
        }
    ]
}

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

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 full name.

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

Customer's billing name/address.

shippingAddresses

List of saved shipping addresses for the customer.

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

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

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

List of customer's favorite products.

billingPerson

Field
Type
Description

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.

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:

  • ec.apps@lightspeedhq.com 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

Last updated 1 month ago

Was this helpful?

array of objects

object

array of objects

array of objects

Defines if customer is tax exempt. Requires a valid tax ID. Read more about handling tax exempt customers in .

object

array of objects

Help Center
items
billingPerson
shippingAddresses
contacts
stats
favorites