Attribute Groups allow fine-grained access management to a subset of Attributes of a Product.
Attribute Groups allow you to define a set of referenced Attribute Definitions for the purpose of giving one or more dedicated teams access to edit Attribute values in Products and Product Variants for those Attributes in the Merchant Center. Depending on the use case, editing permission can be granted to all Attributes, to Attributes that are ungrouped, or none. Only teams with editing permissions can edit Attributes.
Regardless of the Product Type, Attributes are referenced by their name as it appears in their Attribute Definition. That is, if multiple Product Types define an Attribute with the same name, teams with access to that Attribute can edit Attribute values for Products of any of those Product Types.
A maximum number 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:2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
name ​ | Name of the AttributeGroup. |
description ​ | Description of the AttributeGroup. |
attributes ​Array of AttributeReference​ | Attributes with unique values. |
createdAt ​DateTime​ | Date and time (UTC) the AttributeGroup was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the AttributeGroup. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the AttributeGroup was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the AttributeGroup. |
AttributeReference
key ​String​ | The Attribute's |
AttributeGroupDraft
key ​String​ | User-defined unique identifier for the AttributeGroup. MinLength:2 ​MaxLength: 256 ​Pattern: ^[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 |
results ​Array of AttributeGroup​ | AttributeGroups matching the query. |
AttributeGroupReference
Reference to an AttributeGroup.
id ​String​ | Platform-generated unique identifier of the referenced AttributeGroup. |
typeId ​ | attribute-group Type of referenced resource. |
obj ​ | Contains the representation of the expanded AttributeGroup. Only present in responses to requests with Reference Expansion for AttributeGroup. |
AttributeGroupResourceIdentifier
ResourceIdentifier to an AttributeGroup. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
id ​String​ | Platform-generated unique identifier of the referenced AttributeGroup. Required if |
key ​String​ | User-generated unique identifier of the referenced AttributeGroup. Required if |
typeId ​ | attribute-group Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
Get AttributeGroup
Get AttributeGroup by ID
view_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
view_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
view_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where | 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 ​ | Number of results requested. Default: 20 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
AttributeGroupPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/attribute-groups -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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"
}
]
}
]
}
Check if AttributeGroup exists
Check if AttributeGroup exists by ID
Checks if an AttributeGroup exists for a given id
. Returns a 200 OK
status if the AttributeGroup exists or a 404 Not Found
otherwise.
view_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if AttributeGroup exists by Key
Checks if an AttributeGroup exists for a given key
. Returns 200 OK
status if the AttributeGroup exists or a 404 Not Found
otherwise.
view_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if AttributeGroup exists by Query Predicate
Checks if an AttributeGroup exists for a given Query Predicate. Returns 200 OK
status if any AttributeGroups match the Query Predicate or a 404 Not Found
otherwise.
view_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/attribute-groups -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create AttributeGroup
manage_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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
{
"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
manage_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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
{
"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
manage_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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
{
"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 2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
{
"action": "setKey",
"key": "k2"
}
Change Name
action ​String​ | "changeName" |
name ​ | New value to set. Must not be empty. |
{
"action": "changeName",
"name": {
"en": "Attribute Group"
}
}
Set Description
action ​String​ | "setDescription" |
description ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setDescription",
"description": {
"en": "Description"
}
}
Add Attribute
action ​String​ | "addAttribute" |
attribute ​ | Value to add. |
{
"action": "addAttribute",
"attribute": {
"key": "a1"
}
}
Remove Attribute
action ​String​ | "removeAttribute" |
attribute ​ | Value to remove. |
{
"action": "removeAttribute",
"attribute": {
"key": "a0"
}
}
Set Attributes
action ​String​ | "setAttributes" |
attributes ​Array of AttributeReference​ | New unique values to set. |
{
"action": "setAttributes",
"attributes": [
{
"key": "a1"
},
{
"key": "a2"
}
]
}
Delete AttributeGroup
Delete AttributeGroup by ID
manage_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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
manage_attribute_groups:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"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"
}
]
}