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.

Representations

CustomerGroup

CustomerGroup

id
String

Unique ID of the customer group.

version
Int

Current version of the customer group.

key
String

User-defined unique identifier for the customer group.

createdAt
createdByBETA

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

lastModifiedAt
lastModifiedByBETA

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

name
String

Unique within the project.

CustomerGroupDraft

key
String

User-defined unique identifier for the customer group.

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

CustomerGroupPagedQueryResponse

PagedQueryResult with results containing an array of CustomerGroup.

offset
Int

Offset supplied by the client or server default. It is the number of elements skipped, not a page number.

limit
Int

Number of results requested in the query request.

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

Array of CustomerGroups matching the query.

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:

200CustomerGroup

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

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:

200CustomerGroup

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

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.
expand
-
The parameter can be passed multiple times.
sort
-
The parameter can be passed multiple times.
limit
Int

Number of results returned.

offset
Int

Number of results skipped.

withTotal
Boolean

Calculate total number of results.

/^var[.][a-zA-Z0-9]+$/
String

Predicate parameter values.

The parameter can be passed multiple times.
Response:

200CustomerGroupPagedQueryResponse

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

Create a 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:CustomerGroupDraft
Response:

201CustomerGroup

Request Example:cURL
curl -X POST 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

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:
version
Int

Expected version of the customer group on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

List of update actions to be performed on the customer group.

Response:

200CustomerGroup

Request Example:cURL
curl -X POST 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

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:
version
Int

Expected version of the customer group on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

List of update actions to be performed on the customer group.

Response:

200CustomerGroup

Request Example:cURL
curl -X POST 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

Update actions

Change Name

action
String
"changeName"
name
String

User-defined unique name for the customer group.

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

Set Key

key
String

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

action
String
"setKey"
Example: json
{
"action" : "setKey",
"key" : "newKey"
}

Set Custom Type

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

action
String
"setCustomType"

If absent, the custom type and any existing CustomFields are removed.

Valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

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

Set Custom Field

action
String
"setCustomField"
name
String
value
Any

Value must be of type Value. If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Example: json
{
"action" : "setCustomField",
"name" : "ExamplaryStringTypeField",
"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:

200CustomerGroup

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/customer-groups/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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:

200CustomerGroup

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/customer-groups/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2021 commercetools
Privacy PolicyImprint