Attribute Groups

Elevate, May 20-22-2025, Miami Beach, Florida

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​BETA
CreatedBy​

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 name as given in its AttributeDefinition.

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 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​
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 is absent.

key​
String​

User-generated unique identifier of the referenced AttributeGroup. Required if id is absent.

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

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:
200

AttributeGroup

asapplication/json
Request Example:cURL
curl --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:
200

AttributeGroup

asapplication/json
Request Example:cURL
curl --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.
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 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:
Request Example:cURL
curl --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"
        }
      ]
    }
  ]
}

Check if AttributeGroup exists

Check if AttributeGroup exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{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.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/attribute-groups/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if AttributeGroup exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/attribute-groups/key={key}

Checks if an AttributeGroup exists for a given key. Returns 200 OK status if the AttributeGroup exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
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

HEAD
https://api.{region}.commercetools.com/{projectKey}/attribute-groups

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.

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

Query Predicates on Attribute Groups are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/attribute-groups -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

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:AttributeGroupDraftasapplication/json
Response:
201

AttributeGroup

asapplication/json
Request Example:cURL
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
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:AttributeGroupUpdateasapplication/json
Response:
200

AttributeGroup

asapplication/json
Request Example:cURL
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
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:AttributeGroupUpdateasapplication/json
Response:
200

AttributeGroup

asapplication/json
Request Example:cURL
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
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: 2​MaxLength: 256​Pattern: ^[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:
200

AttributeGroup

asapplication/json
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:
200

AttributeGroup

asapplication/json
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"
    }
  ]
}