Product Types

Product types are used to describe common characteristics, most importantly common custom attributes, of many concrete products.

Please note: to customize other resources than products, please refer to types.

Representations

ProductType

  • id - String
    The unique ID of the product type.
  • version - Number
    The current version of the product type.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • key - String - Optional
    User-specific unique identifier for the product type (max. 256 characters).
  • name - String
  • description - String
  • attributes - Array of AttributeDefinition

ProductTypeDraft

  • name - String - Required
  • key - String - Optional
    User-specific unique identifier for the product type (min. 2 and max. 256 characters).
  • description - String - Required
  • attributes - Array of AttributeDefinitionDraft - Optional

AttributeDefinition

Attribute definitions describe a product attribute and allow you to define some 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
    The unique name of the attribute used in the API. The name must be between two and 256 characters long and can contain the ASCII letters A to Z in lowercase or uppercase, digits, underscores (_) and the hyphen-minus (-).
    When using the same name for an attribute in two or more product types all fields of the AttributeDefinition of this attribute need to be the same across the product types, otherwise an AttributeDefinitionAlreadyExists error code will be returned. An exception to this are the values of an enum or lenum type and sets thereof.
  • label - LocalizedString
    A human-readable label for the attribute.
  • isRequired - Boolean
    Whether the attribute is required to have a value.
  • attributeConstraint - AttributeConstraint
    Describes how an attribute or a set of attributes should be validated across all variants of a product.
  • inputTip - LocalizedString - Optional
    Additional information about the attribute that aids content managers when setting product details.
  • inputHint - TextInputHint
    Provides a visual representation type for this attribute. only relevant for text-based attribute types like TextType and LocalizableTextType.
  • isSearchable - Boolean
    Whether the attribute’s values should generally be enabled in product search. This determines whether the value is stored in products for matching terms in the context of full-text search queries and can be used in facets & filters as part of product search queries. The exact features that are enabled/disabled with this flag depend on the concrete attribute type and are described there. The max size of a searchable field is restricted to 10922 characters. 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

AttributeDefinitionDrafts specify the product attribute to be created with the ProductTypeDraft

  • type - AttributeType - Required
    Describes the type of the attribute.
  • name - String - Required
    The unique name of the attribute used in the API. The name must be between two and 256 characters long and can contain the ASCII letters A to Z in lowercase or uppercase, digits, underscores (_) and the hyphen-minus (-).
    When using the same name for an attribute in two or more product types all fields of the AttributeDefinition of this attribute need to be the same across the product types.
  • label - LocalizedString - Required
    A human-readable label for the attribute.
  • isRequired - Boolean - Required
    Whether the attribute is required to have a value.
  • attributeConstraint - AttributeConstraint - Optional, defaults to None
    Describes how an attribute or a set of attributes should be validated across all variants of a product.
  • inputTip - LocalizedString - Optional
    Additional information about the attribute that aids content managers when setting product details.
  • inputHint - TextInputHint - Optional, defaults to SingleLine
    Provides a visual representation type for this attribute. only relevant for text-based attribute types like TextType and LocalizableTextType.
  • isSearchable - Boolean
    Whether the attribute’s values should generally be enabled in product search. This determines whether the value is stored in products for matching terms in the context of full-text search queries and can be used in facets & filters as part of product search queries. The exact features that are enabled/disabled with this flag depend on the concrete attribute type and are described there.

AttributeType

All attribute types have a name. Some have additional fields such as values in enums or elementType in sets.

BooleanType

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

  • name - boolean

TextType

  • name - text

LocalizableTextType

  • name - ltext

EnumType

  • name - enum
  • values - Array of PlainEnumValue
    The available values that can be assigned to products.

LocalizableEnumType

  • name - lenum
  • values - Array of LocalizedEnumValue
    The available values that can be assigned to products.

NumberType

  • name - number

MoneyType

  • name - money

DateType

  • name - date

TimeType

  • name - time

DateTimeType

  • name - datetime

ReferenceType

SetType

The set attribute type defines a set (array without duplicates) with values of the given elementType. It does not support isRequired.

NestedType beta

The nested attribute type allows you to nest attributes based on some existing product type. It does not support isSearchable nor it is supported in queries at the moment. The only supported AttributeConstraint is None.

  • name - nested
  • typeReference - Reference to a ProductType
    ProductType defines, which attributes are allowed to be stored as a 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 array is a JSON object with properties name and value.

Here is an example of nested attribute value in product variant:

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

It is also possible to declare a set of nested attribute type:

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

To get more information about NestedTypes please consult our tutorial dedicated to this.

TextInputHint

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

  • SingleLine
  • MultiLine

PlainEnumValue

A plain enum value has to be unique within the enum, otherwise a DuplicateEnumValues error will be returned.

  • key - String
    The key of the value used as a programmatic identifier, e.g. in facets & filters.
  • label - String
    A descriptive label of the value.

LocalizedEnumValue

A localized enum value has to be unique within the enum, otherwise a DuplicateEnumValues error will be returned.

  • key - String
    The key of the value used as a programmatic identifier, e.g. in facets & filters.
  • label - LocalizedString
    A descriptive, localized label of the value.

AttributeConstraint Enum

AttributeConstraint enum tells 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 value should be different in each variant
  • CombinationUnique - A set of attributes, that have this constraint, should have different combinations in each variant
  • SameForAll - Attribute value should be the same in all variants

Get a ProductType

Get a ProductType by ID

Endpoint: /{projectKey}/product-types/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: ProductType

Get a ProductType by Key

Endpoint: /{projectKey}/product-types/key={key}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: ProductType

Query ProductTypes

Endpoint: /{projectKey}/product-types
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results array of ProductType
Query Parameters:

Create a ProductType

Endpoint: /{projectKey}/product-types
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Request Representation: ProductTypeDraft
Response Representation: ProductType

Update ProductType

Update ProductType by ID

Endpoint: /{projectKey}/product-types/{id}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: ProductType
Fields:

  • version - Number - Required
    The expected version of the product type on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the product type.

Update ProductType by Key

Endpoint: /{projectKey}/product-types/key={key}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: ProductType
Fields:

  • version - Number - Required
    The expected version of the product type on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the product type.

Update Actions

Set Key

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, this field will be removed if it exists. Min. 2 and max. 256 characters

Change Name

  • action - String - "changeName"
  • name - String - Required

Change Description

  • action - String - "changeDescription"
  • description - String - Required

Add AttributeDefinition

Remove AttributeDefinition

Remove an attribute definition.
This removal also deletes all corresponding attributes on all Products with this product type. The removal of the attributes is eventually consistent.

  • action - String - "removeAttributeDefinition"
  • name - String - Required
    The name of the attribute to remove.

Change AttributeDefinition Name

Rename an attribute definition.
This action also renames all corresponding attributes on all Products with this product type. The renaming of the attributes is eventually consistent.

  • action - String - "changeAttributeName"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • newAttributeName - String - Required
    The new name attribute definition name.

warning:

When renaming several attributes at the same time beware of the following effects on updates on the affected products:

  • let’s say we have a product type with 2 attribute definitions: aa and bb.
  • we send a first command to update bb to cc.
  • and then we send a second command to update aa to bb.
  • when updating the products the order is not guaranteed as they are 2 separated commands. It’s possible (even if unlikely) that the products are updated in the wrong order: the attribute aa is renamed to bb, and then to cc.

To avoid that, send multiple "changeAttributeName" updates in one command:

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

In that case, the products are also updated in a guaranteed order.

Change AttributeDefinition Label

  • action - String - "changeLabel"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • label - LocalizedString - Required

Set AttributeDefinition InputTip

Allows to set additional information about the specified attribute that aids content managers when setting product details.

  • action - String - "setInputTip"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • inputTip - LocalizedString - Optional

Add PlainEnumValue to AttributeDefinition

Adds an enum to the values of EnumType. It can update an EnumType attribute definition or a Set of EnumType attribute definition.

  • action - String - "addPlainEnumValue"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • value - PlainEnumValue - Required

Add LocalizableEnumValue to AttributeDefinition

Adds an localizable enum to the values of LocalizableEnumType. It can update a LocalizableEnum attribute definition or a Set of LocalizableEnumType attribute definition.

  • action - String - "addLocalizedEnumValue"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • value - LocalizedEnumValue - Required

Remove EnumValues from AttributeDefinition

Removes enum values from an attribute definition of EnumType or LocalizableEnumType or Set of EnumType or Set of LocalizableEnum.
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 will fail with the EnumValueIsUsed error code.

  • action - String - "removeEnumValues"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • keys - Array of String - Required
    The keys of the EnumType or LocalizableEnumType to remove.

Change the order of AttributeDefinitions

  • action - String - "changeAttributeOrder"
  • attributes - Array of AttributeDefinition - Required
    The attributes must be equal to the product type attributes (except for the order).

Change the order of EnumValues

This action changes the order of enum values in an EnumType attribute definition.

It can update an EnumType attribute definition or a Set of EnumType attribute definition.

  • action - String - "changePlainEnumValueOrder"
  • attributeName - String - Required
  • values - Array of PlainEnumValue - Required
    The values must be equal to the values of the attribute enum values (except for the order). If not a EnumValuesMustMatch error code will be returned.

Change the order of LocalizedEnumValues

This action changes the order of localized enum values in a LocalizableEnumType attribute definition.

It can update a LocalizableEnumType attribute definition or a Set of LocalizableEnumType attribute definition.

  • action - String - "changeLocalizedEnumValueOrder"
  • attributeName - String - Required
  • values - Array of LocalizedEnumValue - Required
    The values must be equal to the values of the attribute enum values (except for the order). If not a EnumValuesMustMatch error code will be returned.

Change the key of an EnumValue

This action changes the key of a single enum value in an EnumType or LocalizableEnumType attribute definition.

It can update an EnumType attribute definition or a LocalizableEnumType attribute definition or a Set of EnumType attribute definition or a Set of LocalizableEnumType attribute definition.

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

  • action - String - "changeEnumKey"
  • attributeName - String - Required
  • key - String - Required
  • newKey - String - Required

Change the label of an EnumValue

This action changes the label of a single enum value in an EnumType attribute definition.

It can update an EnumType attribute definition or a Set of EnumType attribute definition.

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

  • action - String - "changePlainEnumValueLabel"
  • attributeName - String - Required
  • newValue - PlainEnumValue - Required
    The new value must be different from the existing value.

Change the label of a LocalizedEnumValue

This action changes the label of a single enum value in a LocalizableEnumType attribute definition.

It can update a LocalizableEnumType attribute definition or a Set of LocalizableEnumType attribute definition.

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

  • action - String - "changeLocalizedEnumValueLabel"
  • attributeName - String - Required
  • newValue - LocalizedEnumValue - Required
    The new value must be different from the existing value.

Change AttributeDefinition IsSearchable

  • action - String - "changeIsSearchable"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • isSearchable - boolean - Required

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 attribute definitions exceeding this limit will be treated as not searchable and will not be available for full-text search.

Change AttributeDefinition InputHint

This action will update the inputHint of an AttributeDefinition.

  • action - String - "changeInputHint"
  • attributeName - String - Required
    The name of the attribute definition to update. Must be of TextType, LocalizableTextType or SetType of TextType/LocalizableTextType.
  • newValue - TextInputHint - Required

Change AttributeDefinition AttributeConstraint

This action will update the attributeConstraint of an AttributeDefinition. For now only following changes are supported: SameForAll to None and Unique to None.

  • action - String - "changeAttributeConstraint"
  • attributeName - String - Required
    The name of the attribute definition to update.
  • newValue - AttributeConstraint - Required
    For now only None is supported.

Delete ProductType

This request deletes a product type only if it’s not referenced by a product.

Delete ProductType by ID

Endpoint: /{projectKey}/product-types/{id}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

  • version - Number - Required

Delete ProductType by Key

Endpoint: /{projectKey}/product-types/key={key}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

  • version - Number - Required