Attribute Groups

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

AttributeReference

AttributeGroupDraft

AttributeGroupPagedQueryResponse

AttributeGroupReference

AttributeGroupResourceIdentifier

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` LocalizedString	Name of the AttributeGroup.
`description` LocalizedString	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 LastModifiedBy	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` LocalizedString	Name of the AttributeGroup.
`description` LocalizedString	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

Reference to an AttributeGroup.

`id` String	Platform-generated unique identifier of the referenced AttributeGroup.
`typeId` String	`"attribute-group"` References an AttributeGroup.
`obj` AttributeGroup	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` 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

Expansion

The parameter can be passed multiple times.

Response:

200AttributeGroupasapplication/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

Expansion

The parameter can be passed multiple times.

Response:

200AttributeGroupasapplication/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` QueryPredicate	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` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`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.

Response:

200AttributeGroupPagedQueryResponseasapplication/json

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

QueryPredicate

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

Expansion

The parameter can be passed multiple times.

Request Body:AttributeGroupDraftasapplication/json

Response:

201AttributeGroupasapplication/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

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`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 ConcurrentModification error will be returned.
`actions` Array of AttributeGroupUpdateAction	Update actions to be performed on the AttributeGroup.

Response:

200AttributeGroupasapplication/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

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`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 ConcurrentModification error will be returned.
`actions` Array of AttributeGroupUpdateAction	Update actions to be performed on the AttributeGroup.

Response:

200AttributeGroupasapplication/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` LocalizedString	New value to set. Must not be empty.

Example: json

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

Set Description

`action` String	`"setDescription"`
`description` LocalizedString	Value to set. If empty, any existing value will be removed.

Example: json

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

Add Attribute

`action` String	`"addAttribute"`
`attribute` AttributeReference	Value to add.

Example: json

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

Remove Attribute

`action` String	`"removeAttribute"`
`attribute` AttributeReference	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` Expansion	The parameter can be passed multiple times.

Response:

200AttributeGroupasapplication/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` Expansion	The parameter can be passed multiple times.

Response:

200AttributeGroupasapplication/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"
    }
  ]
}