Customer Groups

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCE

A Customer can be a member of multiple Customer Groups. Special prices can be assigned to specific products based on a Customer Group.

A maximum number of 10 000 Customer Groups can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.
Learn more about when to use Customer Groups for discounts versus Channels for negotiated B2B pricing in our self-paced Configure B2B pricing module.

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

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

CustomerGroup

as
application/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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

CustomerGroup

as
application/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
​
String
​
Queryable field: name
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
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.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

CustomerGroupPagedQueryResponse

as
application/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 with the provided id. Returns a 200 status if the CustomerGroup exists, or a 404 status 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 with the provided key. Returns a 200 status if the CustomerGroup exists, or a 404 status 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 one or more CustomerGroups exist for the provided query predicate. Returns a 200 status if any CustomerGroup match the query predicate, or a 404 status 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
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:CustomerGroupDraftasapplication/json
Response:
201

CustomerGroup

as
application/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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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​
Array of CustomerGroupUpdateAction​

Update actions to be performed on the CustomerGroup.

Response:
200

CustomerGroup

as
application/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
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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​
Array of CustomerGroupUpdateAction​

Update actions to be performed on the CustomerGroup.

Response:
200

CustomerGroup

as
application/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: 2​MaxLength: 256​Pattern: ^[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"
type​
TypeResourceIdentifier​
Defines the Type that extends the CustomerGroup with Custom Fields. If absent, any existing Type and Custom Fields are removed from the CustomerGroup.
fields​
FieldContainer​
Object containing the Custom Fields fields for the CustomerGroup.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​
Name of the Custom Field.
value​
CustomFieldValue​
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": "exampleStringField",
  "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
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

CustomerGroup

as
application/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
​
Int64
​

Last seen version of the resource.

expand
​
String
​

Use to expand resources in a single request.

For more information, see Reference Expansion.
The parameter can be passed multiple times.
Response:
200

CustomerGroup

as
application/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"
}

Representations

CustomerGroup

id​
String​

Unique identifier of the CustomerGroup.

version​
Int64​

Current version of the CustomerGroup.

key​
String​

User-defined unique identifier for the CustomerGroup.

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

Unique name of the CustomerGroup.

custom​
CustomFields​

Custom Fields of the CustomerGroup.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the CustomerGroup.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the CustomerGroup.

CustomerGroupDraft

key​
String​

User-defined unique identifier for the CustomerGroup.

MinLength: 2​MaxLength: 256​Pattern: ^[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​
CustomFieldsDraft​

Custom Fields for the CustomerGroup.

CustomerGroupPagedQueryResponse

PagedQueryResult with results containing an array of CustomerGroup.
limit​
Int64​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int64​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int64​

Actual number of results returned.

total​
Int64​
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

Reference to a CustomerGroup.
id​
String​
Unique identifier of the referenced CustomerGroup.
typeId​
ReferenceTypeId​
customer-group
obj​
CustomerGroup​
Contains the representation of the expanded CustomerGroup. Only present in responses to requests with Reference Expansion for CustomerGroups.

CustomerGroupKeyReference

Used by the Import API to identify a CustomerGroup.
key​
String​

User-defined unique identifier of the referenced CustomerGroup.

typeId​
ReferenceType​
customer-group

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​
ReferenceTypeId​
customer-group