This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Customer Groups

A Customer can be a member of a Customer Group (for example, reseller, gold member). Special prices can be assigned to specific products based on a Customer Group.

A maximum number of 1 000 Customer Groups can be created per Project. Learn more about this limit.

Learn more about managing Customer Groups in our self-paced Customer Management module.

Representations

CustomerGroup

id
String

Unique identifier of the CustomerGroup.

version
Int

Current version of the CustomerGroup.

key
String

User-defined unique identifier for the CustomerGroup.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name
String

Unique name of the CustomerGroup.

custom

Custom Fields for the CustomerGroup.

createdAt

Date and time (UTC) the CustomerGroup was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the CustomerGroup was last updated.

lastModifiedByBETA

Present on resources updated after 1 February 2019 except for events not tracked.

CustomerGroupDraft

key
String

User-defined unique identifier for the CustomerGroup.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
groupName
String

Unique value which must be different from any value used for name in CustomerGroup in the Project. If not, a DuplicateField error is returned.

custom

Custom Fields for the CustomerGroup.

CustomerGroupPagedQueryResponse

PagedQueryResult with results containing an array of CustomerGroup.

limit
Int
offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of CustomerGroup

CustomerGroups matching the query.

CustomerGroupReference

id
String

Unique identifier of the referenced CustomerGroup.

typeId
String
"customer-group"

References a CustomerGroup.

obj

Contains the representation of the expanded CustomerGroup. Only present in responses to requests with Reference Expansion for CustomerGroups.

CustomerGroupResourceIdentifier

ResourceIdentifier to a CustomerGroup. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id
String

Unique identifier of the referenced CustomerGroup. Required if key is absent.

key
String

User-defined unique identifier of the referenced CustomerGroup. Required if id is absent.

typeId
String
"customer-group"

References a CustomerGroup.

Get CustomerGroup

Get CustomerGroup by ID

GET
https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id}
OAuth 2.0 Scopes:
view_customers:{projectKey} , view_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the CustomerGroup.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200CustomerGroupasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}

Get CustomerGroup by Key

GET
https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key}
OAuth 2.0 Scopes:
view_customers:{projectKey} , view_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the CustomerGroup.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200CustomerGroupasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}

Query CustomerGroups

GET
https://api.{region}.commercetools.com/{projectKey}/customer-groups
OAuth 2.0 Scopes:
view_customers:{projectKey} , view_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where

Queryable field: name

The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200CustomerGroupPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customer-groups -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomerGroupPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}
]
}

Check if CustomerGroup exists

Check if CustomerGroup exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id}

Checks if a CustomerGroup exists for a given id. Returns a 200 OK status if the CustomerGroup exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_customers:{projectKey} , view_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the CustomerGroup.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if CustomerGroup exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key}

Checks if a CustomerGroup exists for a given key. Returns a 200 OK status if the CustomerGroup exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_customers:{projectKey} , view_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the CustomerGroup.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if CustomerGroup exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/customer-groups

Checks if a CustomerGroup exists for a given Query Predicate. Returns a 200 OK status if any CustomerGroup match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_customers:{projectKey} , view_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/customer-groups -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create CustomerGroup

POST
https://api.{region}.commercetools.com/{projectKey}/customer-groups
OAuth 2.0 Scopes:
manage_customers:{projectKey} , manage_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:CustomerGroupDraftasapplication/json
Response:
201CustomerGroupasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customer-groups -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"groupName" : "Webshop user"
}
DATA
201 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}

Update CustomerGroup

Update CustomerGroup by ID

POST
https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id}
OAuth 2.0 Scopes:
manage_customers:{projectKey} , manage_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the CustomerGroup.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the CustomerGroup on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the CustomerGroup.

Response:
200CustomerGroupasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : "New Name"
} ]
}
DATA
200 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}

Update CustomerGroup by Key

POST
https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key}
OAuth 2.0 Scopes:
manage_customers:{projectKey} , manage_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the CustomerGroup.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the CustomerGroup on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the CustomerGroup.

Response:
200CustomerGroupasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : "New Name"
} ]
}
DATA
200 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}

Update actions

Change Name

action
String
"changeName"
name
String

New name of the CustomerGroup.

Example: json
{
"action": "changeName",
"name": "New Name"
}

Set Key

action
String
"setKey"
key
String

If key is absent or null, the existing key, if any, will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action": "setKey",
"key": "newKey"
}

Set Custom Type

This action sets or removes the custom type for an existing CustomerGroup. If present, this action overwrites any existing custom type and fields.

action
String
"setCustomType"

Defines the Type that extends the CustomerGroup with Custom Fields. If absent, any existing Type and Custom Fields are removed from the CustomerGroup.

fields

Sets the Custom Fields fields for the CustomerGroup.

Example: json
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringTypeField": "TextString"
}
}

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setCustomField",
"name": "ExampleStringTypeField",
"value": "TextString"
}

Delete CustomerGroup

Delete CustomerGroup by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id}
OAuth 2.0 Scopes:
manage_customers:{projectKey} , manage_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the CustomerGroup.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
200CustomerGroupasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}

Delete CustomerGroup by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key}
OAuth 2.0 Scopes:
manage_customers:{projectKey} , manage_customer_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the CustomerGroup.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
200CustomerGroupasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: CustomerGroupjson
{
"id": "aef9cf41-94ad-4794-8122-62d308900430",
"version": 2,
"name": "Webshop user",
"createdAt": "2017-01-10T06:51:25.896Z",
"lastModifiedAt": "2017-01-10T06:51:25.946Z"
}