Product Types

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

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.

To customize resources other than Products, refer to Types.

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

Representations

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

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.

Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​

Number of elements skipped.

Default: 0​Maximum: 10000​
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

id​
String​

Unique identifier of the referenced ProductType.

typeId​
product-type

Type of referenced resource.

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

Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

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​

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​

Human-readable label for the Attribute.

isRequired​
Boolean​

If true, the Attribute must have a value on a ProductVariant.

attributeConstraint​

Specifies how Attributes are validated across all variants of a Product.

inputTip​

Provides additional Attribute information to aid content managers configure Product details.

inputHint​

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 in the Product Projection Search or the Product 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​

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

Human-readable label for the Attribute.

isRequired​
Boolean​

Set to true if the Attribute is required to have a value on a ProductVariant.

attributeConstraint​

Specifies how an Attribute or a combination of Attributes should be validated across all variants of a Product.

Default: None​
inputTip​

Provides additional information about the Attribute that aids content managers when setting Product details.

inputHint​

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 Projection Search or the Product 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​

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​

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​

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​

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​

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​

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
​​
The parameter can be passed multiple times.
Response:
200

ProductType

asapplication/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
​​
The parameter can be passed multiple times.
Response:
200

ProductType

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

ProductTypePagedQueryResponse

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

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
​​
The parameter can be passed multiple times.
Request Body:ProductTypeDraftasapplication/json
Response:
201

ProductType

asapplication/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
​​
The parameter can be passed multiple times.
Request Body:ProductTypeUpdateasapplication/json
Response:
200

ProductType

asapplication/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
​​
The parameter can be passed multiple times.
Request Body:ProductTypeUpdateasapplication/json
Response:
200

ProductType

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

Update actions

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​

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

  1. We send a command to update bb to cc.
  2. 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​

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​

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​

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​

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

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​

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​

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​

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​

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
​​
The parameter can be passed multiple times.
Response:
200

ProductType

asapplication/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
​​
The parameter can be passed multiple times.
Response:
200

ProductType

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