NAV

Customer groups

In Ecwid stores merchants assign customers to specific groups in order to treat them differently. For example, for some group of people, that purchased a membership in their store, they would like to provide a discount based on subtotal at all times. Another way of using customer groups is to to show them a hidden content of a store, in case if these customers are wholesalers.

To manage customer groups in Ecwid stores, use this endpoint described below and to find out more about customer groups in Ecwid stores, check out this page

Get all customer groups

Get information about all customer groups in an Ecwid store.

Request

Request example

GET /api/v3/4870020/customer_groups?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}/customer_groups?offset={offset}&limit={limit}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
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": 2,
    "count": 2,
    "limit": 10,
    "offset": 0,
    "items": [
        {
            "id": 0,
            "name": "General"
        },
        {
            "id": 12345,
            "name": "VIP"
        }
    ]
}

A JSON object of type ‘CustomerGroupsSearchResult’ with the following fields:

CustomerGroupsSearchResult

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

CustomerGroupsSearchEntry

FieldTypeDescription
idnumberUnique internal customer group ID
namestringCustomer group name

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
402Store doesn’t have access to customer groups feature, it’s available on Business plan an higher
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the customer groups info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get customer group

Get information about a specific customer group in an Ecwid store referring to its ID.

Request

Request example

GET /api/v3/4870020/customer_groups/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}/customer_groups/{groupId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
groupIdnumberCustomer group ID
tokenstringoAuth token

Response

Response example (JSON)

{
    "id": 12345,
    "name": "VIP"
}

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

CustomerGroup

FieldTypeDescription
idnumberUnique internal customer group ID
namestringCustomer group name

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
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
404Customer group is not found
500Cannot retrieve the customer info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create customer group

Create a brand new customer group in an Ecwid store.

Request

Request body

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

{
    "name": "Platinum"
}

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

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

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

CustomerGroup

FieldTypeDescription
namestringCustomer group name

Response

Response example

{
    "id": 123456
}

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

CreateStatus

FieldTypeDescription
idnumberID of the created customer group

Errors

Error response example

HTTP/1.1 400 Field CustomerMembership.name is absent
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
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
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 group

Update an existing customer group in an Ecwid store referring to its ID.

Request

Request body

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

{
    "name": "VIP Plus"
}

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

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
groupIdnumberInternal customer group ID

Request body

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

CustomerGroup

FieldTypeDescription
namestringCustomer group name

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
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
404The customer group with given ID is not found
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 group

Delete a customer group in an Ecwid store referring to its ID.

Request example

DELETE /api/v3/4870020/customer_groups/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}/customer_groups/{groupId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
groupIdnumberCustomer 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
402Store doesn’t have access to customer groups feature, it’s available on Business plan and higher
404The customer group with given ID is not found
500The update request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message