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

CustomerGroupDraft

CustomerGroupPagedQueryResponse

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` DateTime
`createdBy`BETA CreatedBy	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime
`lastModifiedBy`BETA LastModifiedBy	Present on resources updated after 1 February 2019 except for events not tracked.
`name` String	Unique within the project.
`custom` CustomFields

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.
`custom` CustomFieldsDraft

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

Expansion

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

Expansion

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` QueryPredicate	Queryable field: `name` The parameter can be passed multiple times.
`expand` Expansion	- The parameter can be passed multiple times.
`sort` 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

Expansion

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

Expansion

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.
`actions` Array of CustomerGroupUpdateAction	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

Expansion

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.
`actions` Array of CustomerGroupUpdateAction	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"`
`type` TypeResourceIdentifier	If absent, the custom type and any existing CustomFields are removed.
`fields` FieldContainer	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` Expansion	- 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` Expansion	- 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}'