Product Types

Representations

ProductType

• id - String
  The unique ID of the Product Type.
• key - String - Optional
  User-specific unique identifier for the Product Type (max. 256 characters).
• version - Number
  The current version of the Product Type.
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• 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 activated 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 activated/deactivated with this flag depend on the concrete attribute type and are described there. The max size of a searchable field is restricted to 10 922 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 - Optional, defaults to true
  Whether the attribute's values should generally be activated 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 activated/deactivated 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

• name - reference
• referenceTypeId - The name of the resource type that the value should reference. Supported values are:
  • "cart"
  • "category"
  • "channel"
  • "customer"
  • "key-value-document"
  • "order"
  • "product"
  • "product-type"
  • "review"
  • "state"
  • "shipping-method"
  • "zone"

SetType

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

• name - set
• elementType - AttributeType

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

As with any other AttributeType, it is possible to declare a set of nested attribute type. However, an iteration of SetType that terminates with a NestedType can have 5 steps at maximum.

{
  "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 the 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, for example 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, for example 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
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: ProductType

Get a ProductType by Key

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

Query ProductTypes

Endpoint: /{projectKey}/product-types
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ProductType
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Create a ProductType

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

Update ProductType

Update ProductType by ID

Endpoint: /{projectKey}/product-types/{id}
Method: POST
OAuth 2.0 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
OAuth 2.0 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, the existing key, if any, will be removed.

Change Name

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

Change Description

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

Add AttributeDefinition

• action - String - "addAttributeDefinition"
• attribute - AttributeDefinitionDraft - Required

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.

The combination unique constraint is not checked when an attribute is removed. When you remove an attribute with combination unique constraint, beware of possible uniqueness violations.

• 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 - "changeAttributeOrderByName"
• attributeNames - Array of [String] - Required
  The names of attributes to reorder. This array must include all attributes currently present on a ProductType in a different 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

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.

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

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
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:

• version - Number - Required

Delete ProductType by Key

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

• version - Number - Required