NAV

Customers

It is possible to place orders without creating an account in a store – it depends on the store settings. Using the methods below you can get information about registered customers and modify them.

Search customers

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

Request

Request examples

GET /api/v3/4870020/customers?email=johnsmith@example.com&token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/customers?keyword={keyword}&name={name}&email={email}&customerGroup={groupId}&minOrderCount={minOrderCount}&maxOrderCount={maxOrderCount}&sortBy={sortBy}&offset={offset}&limit={limit}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
keywordstringSearch term that Ecwid looks for in all customer fields
namestringCustomer name
emailstringCustomer email
groupIdnumberCustomer group ID
minOrderCountnumberMinimum number of order a customer placed
maxOrderCountnumberMaximum number of order a customer placed
createdFromstringCustomer register date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
createdTostringCustomer register date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedFromstringCustomer last update date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedTostringCustomer last update date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
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
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10

Response

Response example (JSON)

{
    "total": 3,
    "count": 3,
    "limit": 100,
    "offset": 0,
    "items": [
        {
            "id": 24623050,
            "name": "Jane Roe",
            "email": "jr@example.com",
            "registered": "2016-01-27 14:06:28 +0000",
            "updated": "2016-01-27 14:06:28 +0000",
            "totalOrderCount": 0,
            "customerGroupId": 0,
            "customerGroupName": "General",
            "billingPerson": {
                "name": "Jane Roe"
            },
            "shippingAddresses": [],
            "taxExempt": false,
            "taxIdValid": true
        },
        {
            "id": 14444116,
            "name": "John Darling [Sample]",
            "email": "demo4@ecwid.com",
            "registered": "2009-07-23 04:59:49 +0000",
            "updated": "2009-07-23 04:59:49 +0000",
            "totalOrderCount": 0,
            "customerGroupId": 2595001,
            "customerGroupName": "Platinum 228",
            "billingPerson": {
                "name": "John Darling [Sample]",
                "street": "12840 Pennridge Dr",
                "city": "Bridgeton",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "63044",
                "stateOrProvinceCode": "MO",
                "stateOrProvinceName": "Missouri",
                "phone": "314-209-0075"
            },
            "shippingAddresses": [],
            "taxExempt": false,
            "taxIdValid": true
        },
        {
            "id": 24623047,
            "name": "John Doe",
            "email": "john@example.com",
            "registered": "2016-01-27 14:06:23 +0000",
            "updated": "2016-01-27 14:06:23 +0000",
            "totalOrderCount": 0,
            "customerGroupId": 0,
            "customerGroupName": "General",
            "billingPerson": {
                "name": "John Doe"
            },
            "shippingAddresses": [],
            "taxExempt": false,
            "taxIdValid": true
        },
        {
            "id": 24623053,
            "name": "John Doe",
            "email": "john@cool.com",
            "registered": "2016-01-27 14:09:36 +0000",
            "updated": "2016-01-27 14:09:36 +0000",
            "totalOrderCount": 0,
            "customerGroupId": 0,
            "customerGroupName": "General",
            "billingPerson": {
                "name": "John Doe"
            },
            "shippingAddresses": [],
            "taxExempt": false,
            "taxIdValid": true
        },
    ]
}

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

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

Q: When does the customer updated date change?

The updated field is changed in these situations:

  • a new customer account created via storefront or via API
  • customer was updated in storefront or via API
  • customer group was changed in any way
  • customer was deleted from Ecwid Control Panel of via API

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

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

Get customer

Get full customers details referring to their ID in an Ecwid store.

Request

Request example

GET /api/v3/4870020/customers/123123?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/customers/{customerId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
customerIdnumberCustomer ID
tokenstringoAuth token

Response

Response example (JSON)

{
    "id": 15319410,
    "email": "johnsmith@example.com",
    "registered": "2014-09-01 23:25:27 +0400",
    "customerGroupId": 12345,
    "customerGroupName": "Extra Gold",
    "billingPerson": {
        "name": "John Smith",
        "companyName": "Unreal Company",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "stateOrProvinceName": "New York",
        "phone": "+1234567890"
    },
    "shippingAddresses": [
        {
            "id": 8315122,
            "name": "John Smith",
            "companyName": "",
            "street": "W 3d st",
            "city": "New York",
            "countryCode": "US",
            "countryName": "United States",
            "postalCode": "10001",
            "stateOrProvinceCode": "NY",
            "phone": "123567890"
        },
        {
            "id": 8315123,
            "name": "Jane Smith",
            "companyName": "",
            "street": "1733 W Madison St",
            "city": "Chicago",
            "countryCode": "US",
            "countryName": "United States",
            "postalCode": "60612",
            "stateOrProvinceCode": "IL",
            "stateOrProvinceName": "Illinois",
            "phone": ""
        }
    ],
    "taxId": "GB999 9999 73",
    "taxExempt": true,
    "taxIdValid": true
}

A JSON object of type 'Customer’ with the following fields:

Customer

FieldTypeDescription
idnumberUnique internal customer ID
emailstringCustomer email
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
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

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

Q: When does the customer updated date change?

The updated field is changed in these situations:

  • a new customer account created via storefront or via API
  • customer was updated in storefront or via API
  • customer group was changed in any way
  • customer was deleted from Ecwid Control Panel of via API

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
404Customer is not found
500Cannot retrieve the customer info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create customer

Create a new customer in an Ecwid store.

Request

Request body

POST /api/v3/4870020/customers?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "email": "example@example.com",
    "password": "ecwidiscool",
    "customerGroupId": 12345,
    "billingPerson": {
        "name": "John Smith",
        "companyName": "Imaginary Company",
        "street": "Hedgehog Street, 1",
        "city": "Bucket",
        "countryCode": "US",
        "postalCode": "90002",
        "stateOrProvinceCode": "CA",
        "phone": "11111111111"
    },
    "shippingAddresses": [
        {
            "name": "John Smith",
            "companyName": "Imaginary Company",
            "street": "W 3d st",
            "city": "New York",
            "countryCode": "US",
            "postalCode": "10001",
            "stateOrProvinceCode": "NY",
            "phone": "11111111111"
        }
      ],
    "taxId": "GB999 9999 73",
    "taxExempt": true,
    "taxIdValid": true
}

POST https://app.ecwid.com/api/v3/{storeId}/customers?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Customer’ with the following fields:

Customer

FieldTypeDescription
emailstringCustomer email
passwordstringCustomer password
customerGroupIdnumberCustomer group ID
billingPersonCustomer’s billing name/address
shippingAddressesArray<ShippingAddress>Customer address book items
taxIdstringCustomer tax ID
taxIdValidbooleantrue if customer tax ID is valid, false otherwise
taxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more

Person

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

ShippingAddress

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

Response

Response example

{
    "id": 15319442
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberID of the created customer

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
409The customer with the given email already exists
415Unsupported content-type: expected application/json or text/json
500The creation request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update customer

Update details of an existing customer in an Ecwid store.

Request

Request body

PUT /api/v3/4870020/customers?10293737&token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "email": "new-email@example.com",
    "password":"newpassword",
    "customerGroupId": 12345,
    "billingPerson": {
        "name": "New Name",
        "companyName": "Ecwid",
        "street": "Updated street",
        "city": "Bucket",
        "countryCode": "US",
        "postalCode": "90002",
        "stateOrProvinceCode": "CA",
        "phone": "11111111111"
    },
    "shippingAddresses": [
        {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "Hedgehog Street, 3",
            "city": "Bucket",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "11111111111"
        }
      ],
    "taxId": "GB999 9999 73",
    "taxExempt": true,
    "taxIdValid": true
}

PUT https://app.ecwid.com/api/v3/{storeId}/customers/{customerId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
customerIdnumberInternal customer ID

Request body

A JSON object of type 'Customer’ with the following fields:

Customer

FieldTypeDescription
emailstringCustomer email
passwordstringCustomer password
customerGroupIdnumberCustomer group ID
billingPersonCustomer’s billing name/address
shippingAddressesArray<ShippingAddress>Customer address book items
taxIdstringCustomer tax ID
taxIdValidbooleantrue if customer tax ID is valid, false otherwise
taxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more

Person

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

ShippingAddress

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

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of update customers (0 or 1 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
404The customer with given ID is not found
409The customer with the given email already exists
415Unsupported content-type: expected application/json or text/json
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete customer

Delete a specific customer from an Ecwid store referring to their ID.

Request example

DELETE /api/v3/4870020/customers/39847403?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/customers/{customerId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
customerIdnumberCustomer ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted customers (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
404The customer with given ID is not found
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message