Product Types

Product Types are used to describe common characteristics, most importantly common custom Attributes, of many concrete Products.

Deciding which aspects of your product catalog to model as Product Type attributes is an important part of working with the API. For more information, see the Product Modeling Module.

A maximum number of 1 000 ProductTypes can be created per Project. Learn more about this limit.

Please note: to customize other resources than Products, please refer to Types.

Learn more about Product Types in our self-paced Product data modeling module.

ProductType

`id` String	Unique identifier of the ProductType.
`version` Int	Current version of the ProductType.
`key` String	User-defined unique identifier of the ProductType. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` String	Name of the ProductType.
`description` String	Description of the ProductType.
`attributes` Array of AttributeDefinition	Attributes specified for the ProductType.
`createdAt` DateTime	Date and time (UTC) the ProductType was initially created.
`createdBy`BETA CreatedBy	IDs and references that created the ProductType.
`lastModifiedAt` DateTime	Date and time (UTC) the ProductType was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the ProductType.

ProductTypeDraft

`key` String	User-defined unique identifier for the ProductType. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` String	Name of the ProductType.
`description` String	Description of the ProductType.
`attributes` Array of AttributeDefinitionDraft	Attributes to specify for the ProductType. Products of this ProductType have these Attributes available on their ProductVariants.

ProductTypePagedQueryResponse

PagedQueryResult with results containing an array of ProductType.

`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`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 ProductType	ProductTypes matching the query.

ProductTypeReference

Reference to a ProductType.

`id` String	Unique identifier of the referenced ProductType.
`typeId` ReferenceTypeId	`"product-type"` References a ProductType.
`obj` ProductType	Contains the representation of the expanded ProductType. Only present in responses to requests with Reference Expansion for ProductTypes.

ProductTypeResourceIdentifier

ResourceIdentifier to a ProductType. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

`id` String	Unique identifier of the referenced ProductType. Required if `key` is absent.
`key` String	User-defined unique identifier of the referenced ProductType. Required if `id` is absent.
`typeId` ReferenceTypeId	`"product-type"` References a ProductType.

AttributeDefinition

Describes a Product Attribute and allows you to define meta-information associated with the Attribute (like whether it should be searchable, or its constraints).

`type` AttributeType	Describes the Type of the Attribute.
`name` String	User-defined name of the Attribute that is unique within the Project. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`label` LocalizedString	Human-readable label for the Attribute.
`isRequired` Boolean	If `true`, the Attribute must have a value on a ProductVariant.
`attributeConstraint` AttributeConstraintEnum	Specifies how Attributes are validated across all variants of a Product.
`inputTip` LocalizedString	Provides additional Attribute information to aid content managers configure Product details.
`inputHint` TextInputHint	Provides a visual representation directive for values of this Attribute (only relevant for AttributeTextType and AttributeLocalizableTextType).
`isSearchable` Boolean	If `true`, the Attribute's values are available for the Product Projections Search API for use in full-text search queries, filters, and facets. Which exact features are available with this flag depends on the specific AttributeType. The maximum size of a searchable field is restricted by the Field content size limit. This constraint is enforced at both Product creation and Product update. If the length of the input exceeds the maximum size, an InvalidField error is returned.

AttributeDefinitionDraft

Specify the Attribute to be created with the ProductTypeDraft.

`type` AttributeType	Describes the Type of the Attribute. When the `type` is different for an AttributeDefinition using the same name in multiple ProductTypes, an AttributeDefinitionTypeConflict error is returned.
`name` String	User-defined name of the Attribute that is unique with the Project. When using the same `name` for an Attribute in multiple ProductTypes, all fields of the AttributeDefinition of this Attribute must be the same across the ProductTypes, else an AttributeDefinitionAlreadyExists error is returned. An exception to this are the values of an `enum` or `lenum` Type and sets thereof. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`label` LocalizedString	Human-readable label for the Attribute.
`isRequired` Boolean	Set to `true` if the Attribute is required to have a value on a ProductVariant.
`attributeConstraint` AttributeConstraintEnum	Specifies how an Attribute or a combination of Attributes should be validated across all variants of a Product. Default: `None`
`inputTip` LocalizedString	Provides additional information about the Attribute that aids content managers when setting Product details.
`inputHint` TextInputHint	Provides a visual representation directive for values of this Attribute (only relevant for AttributeTextType and AttributeLocalizableTextType). Default: `SingleLine`
`isSearchable` Boolean	Set to `true` if the Attribute's values should be available in the Product Projections Search API and can be used in full-text search queries, filters, and facets. Which exact features are available with this flag depends on the specific AttributeType. The maximum size of a searchable field is restricted by the Field content size limit. This constraint is enforced at both Product creation and Product update. If the length of the input exceeds the maximum size, an InvalidField error is returned. Default: `true`

AttributeType

Attributes are classified based on the data type the Attribute values hold. All Attribute types have a name. Some have additional fields such as values in enums or elementType in sets.

AttributeBooleanType

Attribute type for Boolean values. Valid values for the Attribute are true and false (JSON Boolean).

name

String

"boolean"

AttributeTextType

Attribute type for plain text values.

name

String

"text"

AttributeLocalizableTextType

Attribute type for LocalizedString values.

name

String

"ltext"

AttributeEnumType

Attribute type for plain enum values. Useful for predefined language-agnostic values selectable in drop downs when only one value should be selected. Use AttributeSetType of AttributeEnumType instead if multiple values can be selected from the list.

`name` String	`"enum"`
`values` Array of AttributePlainEnumValue	Available values that can be assigned to Products.

AttributeLocalizedEnumType

Attribute type for localized enum values. Useful for predefined language-specific values selectable in drop-down menus if only one value can be selected. Use AttributeSetType of AttributeLocalizedEnumValue instead if multiple values can be selected.

`name` String	`"lenum"`
`values` Array of AttributeLocalizedEnumValue	Available values that can be assigned to Products.

AttributeNumberType

name

String

"number"

AttributeMoneyType

name

String

"money"

AttributeDateType

name

String

"date"

AttributeTimeType

name

String

"time"

AttributeDateTimeType

name

String

"datetime"

AttributeReferenceType

`name` String	`"reference"`
`referenceTypeId` AttributeReferenceTypeId	Name of the resource type that the value should reference.

AttributeSetType

AttributeType that defines a set (without duplicate elements) with values of the given elementType. It does not support isRequired. Since this type itself is an AttributeType, it is possible to construct an AttributeSetType of an AttributeSetType of any AttributeType, and to continue with this iteration until terminating with any non-AttributeSetType. In case the AttributeSetType iteration terminates with an AttributeNestedType, the iteration can have 5 steps at maximum.

`name` String	`"set"`
`elementType` AttributeType	Attribute type of the elements in the set.

AttributeNestedType BETA

Attribute type for nesting Attributes based on some existing ProductType. It does not support isSearchable and is not supported in queries. The only supported AttributeConstraint is None.

`name` String	`"nested"`
`typeReference` ProductTypeReference	Attributes that can be stored as nested Attributes of the current Attribute.

The value of the nested Attribute is an array of values. It reflects the structure of the attributes property of Product Variant, where every element of the array is a JSON object with properties name and value.

Here is an example of nested Attribute values in a Product Variant:

{
  ...
  "attributes": [
    {"name": "nutrients", "value": [
      {"name": "servingSize", "value": 100},
      {"name": "servingSizeUnits", "value": "GR" }
    ]}
  ]
  ...
}

As with any other AttributeType, it is possible to declare a set of nested Attribute Type. However, an iteration of AttributeSetType that terminates with an AttributeNestedType is limited to 5 steps.

{
  "name": "productTypeWithNestedSet",
  "type": {
    "name": "set",
    "elementType": {
      "name": "nested",
      "typeReference": {
        "id": "<id-nested-product-type>",
        "typeId": "product-type"
      }
    }
  }
}

Consult the Nested types tutorial for more information.

AttributePlainEnumValue

A plain enum value must be unique within the enum, else a DuplicateEnumValues error is returned.

`key` String	Key of the value used as a programmatic identifier, for example in facets & filters.
`label` String	Descriptive label of the value.

AttributeLocalizedEnumValue

A localized enum value must be unique within the enum, else a DuplicateEnumValues error is returned.

`key` String	Key of the value used as a programmatic identifier, for example in facets & filters.
`label` LocalizedString	Descriptive, localized label of the value.

AttributeConstraintEnum

Specifies how an Attribute (or a set of Attributes) should be validated across all variants of a Product:

None: No constraints are applied to the Attribute.
Unique: Attribute values must be different for each variant.
CombinationUnique: Set of Attributes that have this constraint, should have different combinations in each variant.
SameForAll: Attribute value should be the same in all variants.

AttributeReferenceTypeId

Name of the resource type that the value should reference. Supported resource type identifiers:

associate-role: References a AssociateRole.
business-unit: References a BusinessUnit.
cart: References a Cart.
cart-discount: References a CartDiscount.
category: References a Category.
channel: References a Channel.
customer: References a Customer.
customer-group: References a CustomerGroup.
key-value-document: References a CustomObject.
order: References an Order.
product: References a Product.
product-type: References a ProductType.
review: References a Review.
shipping-method: References a ShippingMethod.
state: References a State.
zone: References a Zone.

TextInputHint

A text input hint is a string with one of the following values:

SingleLine: Hint for GUIs to display the field's content in a single line of text.
MultiLine: Hint for GUIs to display the field's content over multiple lines of text.

Get ProductType

Get ProductType by ID

GET

https://api.{region}.commercetools.com/{projectKey}/product-types/{id}

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ProductType.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductTypeasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/product-types/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Get ProductType by Key

GET

https://api.{region}.commercetools.com/{projectKey}/product-types/key={key}

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the ProductType.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ProductTypeasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/product-types/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Query ProductTypes

GET

https://api.{region}.commercetools.com/{projectKey}/product-types

OAuth 2.0 Scopes:

view_products:{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. Default: `true`

Response:

200ProductTypePagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/product-types -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ProductTypePagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "d2220bf39eb2-c2f93298-c967-44af-8c2a",
      "version": 1,
      "name": "test_product_type",
      "description": "Test product type.",
      "attributes": [
        {
          "type": {
            "name": "text"
          },
          "isSearchable": false,
          "inputHint": "SingleLine",
          "name": "size",
          "label": {
            "en": "The right size is important."
          },
          "isRequired": false,
          "attributeConstraint": "CombinationUnique"
        }
      ],
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "1970-01-01T00:00:00.001Z"
    },
    {
      "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
      "version": 1,
      "name": "another-test_product_type",
      "description": "Another test product type.",
      "attributes": [
        {
          "type": {
            "name": "text"
          },
          "isSearchable": false,
          "inputHint": "SingleLine",
          "name": "color",
          "label": {
            "en": "The right color is important."
          },
          "isRequired": false,
          "attributeConstraint": "CombinationUnique"
        }
      ],
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "1970-01-01T00:00:00.001Z"
    }
  ]
}

Check if ProductType exists

Check if ProductType exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/product-types/{id}

Checks if a ProductType exists for a given id. Returns a 200 OK status if the ProductType exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ProductType.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/product-types/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ProductType exists by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/product-types/key={key}

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

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the ProductType.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/product-types/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ProductType exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/product-types

Checks if a ProductType exists for a given Query Predicate. Returns a 200 OK status if any ProductTypes match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{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 Product Attributes are limited to text, enum, boolean, number, date, time, and datetime attribute types.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/product-types -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create ProductType

POST

https://api.{region}.commercetools.com/{projectKey}/product-types

OAuth 2.0 Scopes:

manage_products:{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:ProductTypeDraftasapplication/json

Response:

201ProductTypeasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/product-types -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "test_product_type",
  "description" : "Test product type.",
  "attributes" : [ {
    "type" : {
      "name" : "text"
    },
    "isSearchable" : false,
    "inputHint" : "SingleLine",
    "name" : "size",
    "label" : {
      "en" : "The right size is important."
    },
    "isRequired" : false,
    "attributeConstraint" : "CombinationUnique"
  } ]
}
DATA

201 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update ProductType

Update ProductType by ID

POST

https://api.{region}.commercetools.com/{projectKey}/product-types/{id}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ProductType.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`version` Int	Expected version of the ProductType 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 ProductTypeUpdateAction	Update actions to be performed on the ProductType.

Response:

200ProductTypeasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/product-types/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "changeName",
    "name" : "new-product-type-name"
  } ]
}
DATA

200 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Update ProductType by Key

POST

https://api.{region}.commercetools.com/{projectKey}/product-types/key={key}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the ProductType.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`version` Int	Expected version of the ProductType 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 ProductTypeUpdateAction	Update actions to be performed on the ProductType.

Response:

200ProductTypeasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/product-types/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "changeName",
    "name" : "new-product-type-name"
  } ]
}
DATA

200 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Set Key

`action` String	`"setKey"`
`key` String	Value to set. If empty, any existing value will be removed. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "setKey",
  "key": "myNewKey"
}

Change Name

`action` String	`"changeName"`
`name` String	New value to set.

Example: json

{
  "action": "changeName",
  "name": "New Product Type name"
}

Change Description

`action` String	`"changeDescription"`
`description` String	New value to set.

Example: json

{
  "action": "changeDescription",
  "description": "New Product Type description"
}

Add AttributeDefinition

`action` String	`"addAttributeDefinition"`
`attribute` AttributeDefinitionDraft	Value to append to `attributes`.

Example: json

{
  "action": "addAttributeDefinition",
  "attribute": {
    "type": {
      "name": "text"
    },
    "name": "your-attribute-name",
    "label": {
      "en": "English label",
      "de": "German label"
    },
    "isRequired": false,
    "attributeConstraint": "None",
    "inputTip": {
      "en": "English input tip",
      "de": "German input tip"
    },
    "inputHint": "SingleLine",
    "isSearchable": true
  }
}

Remove AttributeDefinition

Removes an AttributeDefinition and also deletes all corresponding Attributes on all Products with this ProductType. The removal of the Attributes is eventually consistent.

The CombinationUnique constraint is not checked when an Attribute is removed, and uniqueness violations may occur when you remove an Attribute with a CombinationUnique constraint.

`action` String	`"removeAttributeDefinition"`
`name` String	Name of the Attribute to remove. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "removeAttributeDefinition",
  "name": "your-attribute-name"
}

Change AttributeDefinition Name

Renames an AttributeDefinition and also renames all corresponding Attributes on all Products with this ProductType. The renaming of the Attributes is eventually consistent.

If the AttributeDefinition name to be changed does not exist, an AttributeNameDoesNotExist error is returned.

`action` String	`"changeAttributeName"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`newAttributeName` String	New user-defined name of the Attribute that is unique with the Project. When using the same `name` for an Attribute in two or more ProductTypes, all fields of the AttributeDefinition of this Attribute must be the same across the ProductTypes. If not, an AttributeDefinitionAlreadyExists error is returned. An exception to this are the values of an `enum` or `lenum` type and sets thereof. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "changeAttributeName",
  "attributeName": "your-attribute-name",
  "newAttributeName": "new-attribute-name"
}

When renaming multiple Attributes, you must consider the impact of these updates on Products.

For example: If there is a ProductType with the Attribute definitions aa and bb:

We send a command to update bb to cc.
We send another command to update aa to bb.

When updating Products, the order is not guaranteed because these are two separate commands.

It is possible (though unlikely) that the Products are updated in the wrong order: the Attribute aa is renamed to bb, and then to cc.

To avoid this outcome, add both "changeAttributeName" update actions to actions. This ensures that Products are updated in the correct order:

{
  "version": "<version>",
  "actions": [
    {
      "action": "changeAttributeName",
      "attributeName": "bb",
      "newAttributeName": "cc"
    },
    {
      "action": "changeAttributeName",
      "attributeName": "aa",
      "newAttributeName": "bb"
    }
  ]
}

Change AttributeDefinition Label

`action` String	`"changeLabel"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`label` LocalizedString	New value to set. Must not be empty.

Example: json

{
  "action": "changeLabel",
  "attributeName": "your-attribute-name",
  "label": {
    "en": "New English label",
    "de": "New German label"
  }
}

Set AttributeDefinition InputTip

`action` String	`"setInputTip"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`inputTip` LocalizedString	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setInputTip",
  "attributeName": "your-attribute-name",
  "inputTip": {
    "en": "New English input tip",
    "de": "New German input tip"
  }
}

Add PlainEnumValue to AttributeDefinition

Adds an enum to the values of AttributeEnumType AttributeDefinition, or AttributeSetType of AttributeEnumType AttributeDefinition.

`action` String	`"addPlainEnumValue"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`value` AttributePlainEnumValue	Value to append to the array.

Example: json

{
  "action": "addPlainEnumValue",
  "attributeName": "your-attribute-name",
  "value": {
    "key": "New enum key",
    "label": "New enum label"
  }
}

Add LocalizableEnumValue to AttributeDefinition

Adds a localizable enum to the values of AttributeLocalizedEnumType. It can update an AttributeLocalizedEnumType AttributeDefinition or an AttributeSetType of AttributeLocalizedEnumType AttributeDefinition.

`action` String	`"addLocalizedEnumValue"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`value` AttributeLocalizedEnumValue	Value to append to the array.

Example: json

{
  "action": "addLocalizedEnumValue",
  "attributeName": "your-attribute-name",
  "value": {
    "key": "New localized enum key",
    "label": {
      "en": "New English enum label",
      "de": "New German enum label"
    }
  }
}

Remove EnumValues from AttributeDefinition

Removes enum values from an AttributeDefinition of AttributeEnumType, AttributeLocalizedEnumType, AttributeSetType of AttributeEnumType, or AttributeSetType of AttributeLocalizedEnumType.

If the Attribute is not required, the Attributes of all Products using those enum keys will also be removed in an eventually consistent way. If the Attribute is required, the operation returns an EnumValueIsUsed error.

`action` String	`"removeEnumValues"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`keys` Array of String	Keys of AttributeEnumType or AttributeLocalizedEnumType to remove.

Example: json

{
  "action": "removeEnumValues",
  "attributeName": "your-attribute-name",
  "keys": [
    "enum key to remove 1",
    "enum key to remove 2",
    "enum key to remove 3"
  ]
}

Change the order of AttributeDefinitions

`action` String	`"changeAttributeOrderByName"`
`attributeNames` Array of String	Names of Attributes to reorder. This array must include all Attributes currently present on a ProductType in a different order.

Example: json

{
  "action": "changeAttributeOrderByName",
  "attributeNames": [
    "your-new-first-attribute",
    "your-new-second-attribute",
    "your-new-third-attribute"
  ]
}

Change the order of EnumValues

Updates the order of enum values in an AttributeEnumType AttributeDefinition. It can update an AttributeEnumType AttributeDefinition or an AttributeSetType of AttributeEnumType AttributeDefinition.

`action` String	`"changePlainEnumValueOrder"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`values` Array of AttributePlainEnumValue	Values must be equal to the values of the Attribute enum values (except for the order). If not, an EnumValuesMustMatch error is returned.

Example: json

{
  "action": "changePlainEnumValueOrder",
  "attributeName": "your-attribute-name",
  "values": [
    {
      "key": "enum key 1",
      "label": "enum value 1"
    },
    {
      "key": "enum key 2",
      "label": "enum value 2"
    },
    {
      "key": "enum key 3",
      "label": "enum value 3"
    }
  ]
}

Change the order of LocalizedEnumValues

Updates the order of localized enum values in an AttributeLocalizedEnumType AttributeDefinition. It can update an AttributeLocalizedEnumType AttributeDefinition or an AttributeSetType of AttributeLocalizedEnumType AttributeDefinition.

`action` String	`"changeLocalizedEnumValueOrder"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`values` Array of AttributeLocalizedEnumValue	Values must be equal to the values of the Attribute enum values (except for the order). If not, an EnumValuesMustMatch error is returned.

Example: json

{
  "action": "changeLocalizedEnumValueOrder",
  "attributeName": "your-attribute-name",
  "values": [
    {
      "key": "localized enum key 1",
      "label": {
        "en": "English label for enum key 1",
        "de": "German label for enum key 1"
      }
    },
    {
      "key": "localized enum key 2",
      "label": {
        "en": "English label for enum key 2",
        "de": "German label for enum key 2"
      }
    },
    {
      "key": "localized enum key 3",
      "label": {
        "en": "English label for enum key 3",
        "de": "German label for enum key 3"
      }
    }
  ]
}

Change the key of an EnumValue

Updates the key of a single enum value in an AttributeEnumType AttributeDefinition, AttributeLocalizedEnumType AttributeDefinition, AttributeSetType of AttributeEnumType AttributeDefinition, or AttributeSetType of AttributeLocalizedEnumType AttributeDefinition.

If the AttributeDefinition does not contain an enum with the referenced key, a EnumKeyDoesNotExist error is returned.

All Products will be updated to the new key in an eventually consistent way.

`action` String	`"changeEnumKey"`
`key` String	Existing key to be changed.
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`newKey` String	New key to be set.

Example: json

{
  "action": "changeEnumKey",
  "attributeName": "your-attribute-name",
  "key": "current enum key",
  "newKey": "new enum key"
}

Change the label of an EnumValue

Updates the label of a single enum value in an AttributeEnumType AttributeDefinition, or AttributeSetType of AttributeEnumType AttributeDefinition.

All Products will be updated to the new label in an eventually consistent way.

`action` String	`"changePlainEnumValueLabel"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`newValue` AttributePlainEnumValue	New value to set. Must be different from the existing value.

Example: json

{
  "action": "changePlainEnumValueLabel",
  "attributeName": "your-attribute-name",
  "newValue": {
    "key": "existing enum key",
    "label": "new label for this enum"
  }
}

Change the label of a LocalizedEnumValue

Updates the label of a single enum value in an AttributeLocalizedEnumType AttributeDefinition, or AttributeSetType of AttributeLocalizedEnumType AttributeDefinition.

All Products will be updated to the new label in an eventually consistent way.

`action` String	`"changeLocalizedEnumValueLabel"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`newValue` AttributeLocalizedEnumValue	New value to set. Must be different from the existing value.

Example: json

{
  "action": "changeLocalizedEnumValueLabel",
  "attributeName": "your-attribute-name",
  "newValue": {
    "key": "existing localized enum key",
    "label": {
      "en": "new English label for this enum",
      "de": "new German label for this enum"
    }
  }
}

Change AttributeDefinition IsSearchable

Following this update the Products are reindexed asynchronously to reflect this change on the search endpoint. When enabling search on an existing Attribute type definition, the constraint regarding the maximum size of a searchable Attribute will not be enforced. Instead, Product AttributeDefinitions exceeding this limit will be treated as not searchable and will not be available for full-text search.

`action` String	`"changeIsSearchable"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`isSearchable` Boolean	Determines whether the Attribute's values can be used in full-text search queries, filters, and facets. See AttributeDefinition for details.

Example: json

{
  "action": "changeIsSearchable",
  "attributeName": "your-attribute-name",
  "isSearchable": false
}

Change AttributeDefinition InputHint

Updates the inputHint of an AttributeDefinition.

`action` String	`"changeInputHint"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`newValue` TextInputHint	`SingleLine` or `MultiLine`

Example: json

{
  "action": "changeInputHint",
  "attributeName": "your-attribute-name",
  "newValue": "MultiLine"
}

Change AttributeDefinition AttributeConstraint

Updates the attributeConstraint of an AttributeDefinition. For now only following changes are supported: SameForAll to None and Unique to None.

`action` String	`"changeAttributeConstraint"`
`attributeName` String	Name of the AttributeDefinition to update. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`newValue` AttributeConstraintEnumDraft	`None`

Example: json

{
  "action": "changeAttributeConstraint",
  "attributeName": "your-attribute-name",
  "newValue": "None"
}

Delete ProductType

ProductTypes can only be deleted if they are not referenced by a Product.

Delete ProductType by ID

DELETE

https://api.{region}.commercetools.com/{projectKey}/product-types/{id}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ProductType.

Query parameters:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200ProductTypeasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/product-types/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Delete ProductType by Key

DELETE

https://api.{region}.commercetools.com/{projectKey}/product-types/key={key}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the ProductType.

Query parameters:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200ProductTypeasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/product-types/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ProductTypejson

{
  "id": "c2f93298-c967-44af-8c2a-d2220bf39eb2",
  "version": 1,
  "name": "test_product_type",
  "description": "Test product type.",
  "attributes": [
    {
      "type": {
        "name": "text"
      },
      "isSearchable": false,
      "inputHint": "SingleLine",
      "name": "size",
      "label": {
        "en": "The right size is important."
      },
      "isRequired": false,
      "attributeConstraint": "CombinationUnique"
    }
  ],
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z"
}

Product Types

Representations

ProductType

ProductTypeDraft

ProductTypePagedQueryResponse

ProductTypeReference

ProductTypeResourceIdentifier

AttributeDefinition

AttributeDefinitionDraft

AttributeType

AttributeBooleanType

AttributeTextType

AttributeLocalizableTextType

AttributeEnumType

AttributeLocalizedEnumType

AttributeNumberType

AttributeMoneyType

AttributeDateType

AttributeTimeType

AttributeDateTimeType

AttributeReferenceType

AttributeSetType

AttributeNestedType BETA

AttributePlainEnumValue

AttributeLocalizedEnumValue

AttributeConstraintEnum

AttributeReferenceTypeId

TextInputHint

Get ProductType

Get ProductType by ID

Get ProductType by Key

Query ProductTypes

Check if ProductType exists

Check if ProductType exists by ID

Check if ProductType exists by Key

Check if ProductType exists by Query Predicate

Create ProductType

Update ProductType

Update ProductType by ID

Update ProductType by Key

Update actions

Set Key

Change Name

Change Description

Add AttributeDefinition

Remove AttributeDefinition

Change AttributeDefinition Name

Change AttributeDefinition Label

Set AttributeDefinition InputTip

Add PlainEnumValue to AttributeDefinition

Add LocalizableEnumValue to AttributeDefinition

Remove EnumValues from AttributeDefinition

Change the order of AttributeDefinitions

Change the order of EnumValues

Change the order of LocalizedEnumValues

Change the key of an EnumValue

Change the label of an EnumValue

Change the label of a LocalizedEnumValue

Change AttributeDefinition IsSearchable

Change AttributeDefinition InputHint

Change AttributeDefinition AttributeConstraint

Delete ProductType

Delete ProductType by ID

Delete ProductType by Key