This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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.

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name
String

Name of the ProductType.

description
String

Description of the ProductType.

attributes

Attributes specified for the ProductType.

createdAt

Date and time (UTC) the ProductType was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the ProductType was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

ProductTypeDraft

key
String

User-defined unique identifier for the ProductType.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name
String

Name of the ProductType.

description
String

Description of the ProductType.

attributes

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

id
String

Unique identifier of the referenced ProductType.

typeId
String
"product-type"

References a ProductType.

obj

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
String
"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

Describes the Type of the Attribute.

name
String

User-defined name of the Attribute that is unique within the Project.

MinLength: 2MaxLength: 256Pattern: ^[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 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

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: 2MaxLength: 256Pattern: ^[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 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

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.

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:
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
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
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
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
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:
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

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

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

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

Update actions

Set Key

action
String
"setKey"
key
String

Value to set. If empty, any existing value will be removed.

MinLength: 2MaxLength: 256Pattern: ^[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"

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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$

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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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": "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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$

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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$

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