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

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	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the AttributeGroup was last updated.
`lastModifiedBy`BETA LastModifiedBy	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: `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.

`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

Expansion

The parameter can be passed multiple times.

Response:

200AttributeGroup

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:

200AttributeGroup

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:

200AttributeGroupPagedQueryResponse

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"
    } ]
  } ]
}

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 409 Conflict 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 409 Conflict 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:

200AttributeGroup

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:

200AttributeGroup

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"
  } ]
}

Attribute Groups

Representations.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}.css-e0dnmk{cursor:pointer;}

AttributeGroup.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

AttributeReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

AttributeGroupDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

AttributeGroupPagedQueryResponse.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

AttributeGroupReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

AttributeGroupResourceIdentifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get AttributeGroup.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get AttributeGroup by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get AttributeGroup by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Query AttributeGroups.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Create AttributeGroup.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update AttributeGroup.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update AttributeGroup by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update AttributeGroup by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update actions.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Name.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Description.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Attribute.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Attribute.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Attributes.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete AttributeGroup.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete AttributeGroup by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete AttributeGroup by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Representations

AttributeGroup

AttributeReference

AttributeGroupDraft

AttributeGroupPagedQueryResponse

AttributeGroupReference

AttributeGroupResourceIdentifier

Get AttributeGroup

Get AttributeGroup by ID

Get AttributeGroup by Key

Query AttributeGroups

Create AttributeGroup

Update AttributeGroup

Update AttributeGroup by ID

Update AttributeGroup by Key

Update actions

Set Key

Change Name

Set Description

Add Attribute

Remove Attribute

Set Attributes

Delete AttributeGroup

Delete AttributeGroup by ID

Delete AttributeGroup by Key