Customer Groups

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. Learn more about this limit.

Representations

CustomerGroup

CustomerGroupDraft

CustomerGroupPagedQueryResponse

CustomerGroupReference

CustomerGroupKeyReference

CustomerGroupResourceIdentifier

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: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` String	Unique name of the CustomerGroup.
`custom` CustomFields	Custom Fields for 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` Int	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10000`
`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

Reference to a CustomerGroup.

`id` String	Unique identifier of the referenced CustomerGroup.
`typeId` ReferenceTypeId	`customer-group` Type of referenced resource.
`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` Type of referenced resource.

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` Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

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

Expansion

The parameter can be passed multiple times.

Response:

200

CustomerGroup

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

Expansion

The parameter can be passed multiple times.

Response:

200

CustomerGroup

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` QueryPredicate	Queryable field: `name` The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	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

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

QueryPredicate

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

Expansion

The parameter can be passed multiple times.

Request Body:CustomerGroupDraftasapplication/json

Response:

201

CustomerGroup

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

Expansion

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` Array of CustomerGroupUpdateAction	Update actions to be performed on the CustomerGroup.

Response:

200

CustomerGroup

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

Expansion

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` Array of CustomerGroupUpdateAction	Update actions to be performed on the CustomerGroup.

Response:

200

CustomerGroup

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	Sets the Custom Fields fields for the CustomerGroup.

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` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200

CustomerGroup

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` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200

CustomerGroup

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

Customer Groups

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomerGroup.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomerGroupDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomerGroupPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomerGroupReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomerGroupKeyReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

CustomerGroupResourceIdentifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get CustomerGroup.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get CustomerGroup by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get CustomerGroup by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Query CustomerGroups.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if CustomerGroup exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if CustomerGroup exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if CustomerGroup exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if CustomerGroup exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create CustomerGroup.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update CustomerGroup.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update CustomerGroup by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update CustomerGroup by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Change Name.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete CustomerGroup.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete CustomerGroup by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete CustomerGroup by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations

CustomerGroup

CustomerGroupDraft

CustomerGroupPagedQueryResponse

CustomerGroupReference

CustomerGroupKeyReference

CustomerGroupResourceIdentifier

Get CustomerGroup

Get CustomerGroup by ID

Get CustomerGroup by Key

Query CustomerGroups

Check if CustomerGroup exists

Check if CustomerGroup exists by ID

Check if CustomerGroup exists by Key

Check if CustomerGroup exists by Query Predicate

Create CustomerGroup

Update CustomerGroup

Update CustomerGroup by ID

Update CustomerGroup by Key

Update actions

Change Name

Set Key

Set Custom Type

Set CustomField

Delete CustomerGroup

Delete CustomerGroup by ID

Delete CustomerGroup by Key