BETA

Attribute Groups

Attribute Groups allow to cluster subsets of Attributes of a Product.

Attribute Groups allow you to define a set of referenced Attribute Definitions for the purpose of easing data enhancement workflows in Product Variants for those Attributes in the Merchant Center. Regardless of the Product Type, Attributes are referenced by their name as it appears in their Attribute Definition.

During the public beta period, a maximum of 100 Attribute Groups can be created per Project.

Representations

AttributeGroup

id
String

Platform-generated unique identifier of the AttributeGroup.

version
Int

Current version of the AttributeGroup.

key
String

User-defined unique identifier of the AttributeGroup.

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

Name of the AttributeGroup.

description

Description of the AttributeGroup.

attributes
Array of AttributeReference

Attributes with unique values.

createdAt

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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

AttributeReference

key
String

Key of the attribute.

AttributeGroupDraft

key
String

User-defined unique identifier for the AttributeGroup.

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

Name of the AttributeGroup.

description

Description of the AttributeGroup.

attributes
Array of AttributeReference

Attributes with unique values.

AttributeGroupPagedQueryResponse

PagedQueryResult with results containing an array of AttributeGroup.

limit
Int

Number of results requested in the query request.

offset
Int

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

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 AttributeGroup

AttributeGroups matching the query.

AttributeGroupReference

id
String

Platform-generated unique identifier of the referenced AttributeGroup.

typeId
String
"attribute-group"

References an AttributeGroup.

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

AttributeGroupResourceIdentifier

id
String

Platform-generated unique identifier of the referenced AttributeGroup. Either id or key is required.

key
String

User-generated unique identifier of the referenced AttributeGroup. Either id or key is required.

typeId
String
"attribute-group"

References an AttributeGroup.

Get AttributeGroup

Get AttributeGroup by ID

GET
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id}
OAuth 2.0 Scopes:
view_attribute_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AttributeGroup.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}

Get AttributeGroup by Key

GET
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key}
OAuth 2.0 Scopes:
view_attribute_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AttributeGroup.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}

Query AttributeGroups

GET
https://api.{region}.commercetools.com/{projectKey}/attribute-groups
OAuth 2.0 Scopes:
view_attribute_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.
/^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.

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/attribute-groups -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AttributeGroupPagedQueryResponsejson
{
"limit" : 20,
"offset" : 0,
"count" : 2,
"total" : 2,
"results" : [ {
"id" : "8406af27-e9ce-43a3-8430-fefbbd8dc70f",
"version" : 1,
"createdAt" : "2022-03-04T11:28:21.623Z",
"lastModifiedAt" : "2022-03-04T11:28:21.623Z",
"lastModifiedBy" : {
"clientId" : "THGlCWh5D1WjiTOzlZedcEx4",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "THGlCWh5D1WjiTOzlZedcEx4",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name 1"
},
"description" : {
"en" : "Sample description 2"
},
"key" : "group-x",
"attributes" : [ {
"key" : "Attribute x1"
}, {
"key" : "Attribute x2"
} ]
}, {
"id" : "e109bb14-f2b4-451a-a44c-8e4755705607",
"version" : 1,
"createdAt" : "2022-03-04T11:28:21.675Z",
"lastModifiedAt" : "2022-03-04T11:28:21.675Z",
"lastModifiedBy" : {
"clientId" : "THGlCWh5D1WjiTOzlZedcEx4",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "THGlCWh5D1WjiTOzlZedcEx4",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name 2"
},
"description" : {
"en" : "Sample description 2"
},
"key" : "group-y",
"attributes" : [ {
"key" : "Attribute y1"
}, {
"key" : "Attribute y2"
} ]
} ]
}

Create AttributeGroup

POST
https://api.{region}.commercetools.com/{projectKey}/attribute-groups
OAuth 2.0 Scopes:
manage_attribute_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:AttributeGroupDraft
Response:
Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/attribute-groups -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-1",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}
DATA
201 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}

Update AttributeGroup

Update AttributeGroup by ID

POST
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id}
OAuth 2.0 Scopes:
manage_attribute_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AttributeGroup.

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

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

actions

Update actions to be performed on the AttributeGroup.

Response:
Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 100,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "Attribute Group"
}
}, {
"action" : "setDescription",
"description" : {
"en" : "Description"
}
}, {
"action" : "setAttributes",
"attributes" : [ {
"key" : "a1"
}, {
"key" : "a2"
} ]
} ]
}
DATA
200 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}

Update AttributeGroup by Key

POST
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key}
OAuth 2.0 Scopes:
manage_attribute_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AttributeGroup.

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

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

actions

Update actions to be performed on the AttributeGroup.

Response:
Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 100,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "Attribute Group"
}
}, {
"action" : "setDescription",
"description" : {
"en" : "Description"
}
}, {
"action" : "setAttributes",
"attributes" : [ {
"key" : "a1"
}, {
"key" : "a2"
} ]
} ]
}
DATA
200 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}

Update actions

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

Change Name

action
String
"changeName"
name

New value to set. Must not be empty.

Example: json
{
"action" : "changeName",
"name" : {
"en" : "Attribute Group"
}
}

Set Description

action
String
"setDescription"
description

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setDescription",
"description" : {
"en" : "Description"
}
}

Add Attribute

action
String
"addAttribute"
attribute

Value to add.

Example: json
{
"action" : "addAttribute",
"attribute" : {
"key" : "a1"
}
}

Remove Attribute

action
String
"removeAttribute"
attribute

Value to remove.

Example: json
{
"action" : "removeAttribute",
"attribute" : {
"key" : "a0"
}
}

Set Attributes

action
String
"setAttributes"
attributes
Array of AttributeReference

New unique values to set.

Example: json
{
"action" : "setAttributes",
"attributes" : [ {
"key" : "a1"
}, {
"key" : "a2"
} ]
}

Delete AttributeGroup

Delete AttributeGroup by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id}
OAuth 2.0 Scopes:
manage_attribute_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AttributeGroup.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}

Delete AttributeGroup by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key}
OAuth 2.0 Scopes:
manage_attribute_groups:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AttributeGroup.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AttributeGroupjson
{
"id" : "751a034a-8691-4a4d-b7be-2f959cb4b65c",
"version" : 1,
"createdAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedAt" : "2022-03-04T08:48:21.992Z",
"lastModifiedBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"createdBy" : {
"clientId" : "arO9WNyyaG2WF0dGuIRMVyMT",
"isPlatformClient" : false
},
"name" : {
"en" : "Sample name"
},
"description" : {
"en" : "Sample description"
},
"key" : "group-a",
"attributes" : [ {
"key" : "Attribute 1"
}, {
"key" : "Attribute 2"
} ]
}