Types

Types allow you to define additional project-specific fields on resources and data types, so-called "Custom Fields."

commercetools Composable Commerce APIs provide flexible data models that cover a wide range of use cases with the standard fields on the resources and their data objects. However, you might want to add additional fields to resources and data types to better support your usage scenario.

With Types, you can model your own Custom Fields on the data types listed in here.

A Type can contain multiple FieldDefinitions, each of which defines a Custom Field.

FieldDefinition is an analog of AttributeDefinition of Product Types.

Multiple Types can be created for a single resource or data type, but a particular resource or data type can be customized with only one Type at the same time.

The value representations of Custom Fields are separately documented on the Custom Fields page.

Find a step-by-step example on how to use Types and Custom Fields in our respective tutorial.

List of customizable data types

With Types, you can model your own Custom Fields on the following resources and data types:

Representations

FieldType-CustomFieldBooleanType-CustomFieldNumberType-CustomFieldStringType-CustomFieldLocalizedStringtype-CustomFieldEnumType-CustomFieldLocalizedEnumType-CustomFieldMoneyType-CustomFieldDateType-CustomFieldTimeType-CustomFieldDateTimeType-CustomFieldReferenceType-CustomFieldSetType

Type

id
String

Unique identifier of the Type.

version
Int

Current version of the Type.

key
String

User-defined unique identifier of the Type.

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

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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

name

Name of the Type.

description

Description of the Type.

resourceTypeIds
Array of ResourceTypeId

Resources and/or data types for which the Type is defined.

fieldDefinitions
Array of FieldDefinition

Defines Custom Fields.

TypeDraft

key
String

User-defined unique identifier for the Type.

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

Name of the Type.

description

Description of the Type.

resourceTypeIds
Array of ResourceTypeId

Resources and/or data types for which the Type is defined.

fieldDefinitions
Array of FieldDefinition

Defines Custom Fields.

TypePagedQueryResponse

PagedQueryResult with results containing an array of Types.

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of Type

Types matching the query.

TypeReference

id
String

Unique identifier of the referenced Type.

typeId
String
"type"

References a Type.

obj
Type

Contains the representation of the expanded Type. Only present in responses to requests with Reference Expansion for Types.

TypeResourceIdentifier

id
String

Unique identifier of the referenced Type. Either id or key is required.

key
String

User-defined unique identifier of the referenced Type. Either id or key is required.

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

References a Type.

ResourceTypeId

address

Address on Cart, Order, OrderEdit, Customer, and Channel

asset

Asset on Category and ProductVariant

cart-discount

CartDiscount

category

Category

channel

Channel

customer

Customer

customer-group

CustomerGroup

custom-line-item

CustomLineItem on Cart and Order

discount-code

DiscountCode

inventory-entry

InventoryEntry

line-item

LineItem on Cart and Order, and LineItem on ShoppingList

order

Cart and Order. When a Cart is ordered, the CustomFields need to be copied to the Order. For this reason, the Types for a Cart are also valid for an Order, and both Cart and Order are referenced by the same string order.

order-edit

OrderEdit

order-delivery

Delivery

order-parcel

Parcel

order-return-item

ReturnItem

payment

Payment

payment-interface-interaction

InterfaceInteraction on Payment

product-price

Price on ProductVariant

product-selection

ProductSelection

review

Review

shipping-method

ShippingMethod

shopping-list

ShoppingList

shopping-list-text-line-item

TextLineItem on ShoppingList

store

Store

transaction

Transaction on Payment

FieldDefinition

Defines a Custom Field and its meta-information. This FieldDefinition is similar to an AttributeDefinition of Product Types.

type

Data type of the Custom Field to define.

name
String

Name of the Custom Field to define. Must be unique for a given ResourceTypeId. In case there is a FieldDefinition with the same name in another Type, both FieldDefinitions must have the same type.

MinLength: 2MaxLength: 36Pattern: ^[A-Za-z0-9_-]+$
label

A human-readable label for the field.

required
Boolean

Defines whether the field is required to have a value.

inputHint

Must be either SingleLine or MultiLine. Defines the visual representation of the field in user interfaces like the Merchant Center. It is only relevant for string-based FieldTypes like CustomFieldStringType and CustomFieldLocalizedStringType.

TextInputHint

Provides a visual representation type for this field. It is only relevant for string-based field types like CustomFieldStringType and CustomFieldLocalizedStringType. Following values are supported:

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.

FieldType

Abstract parent type for the specific field types with the common name field. Some of the specific field types have additional fields for meta-data, for example, allowed values for enum types or elementType for set type fields.

CustomFieldBooleanType

Field type for Boolean values.

name
String
"Boolean"

CustomFieldNumberType

Field type for number values.

name
String
"Number"

CustomFieldStringType

Field type for string values.

name
String
"String"

CustomFieldLocalizedStringtype

Field type for LocalizedString values.

name
String
"LocalizedString"

CustomFieldEnumType

Field type for enum values.

name
String
"Enum"
values

Allowed values.

CustomFieldLocalizedEnumType

Field type for localized enum values.

name
String
"LocalizedEnum"
values

Allowed values.

CustomFieldMoneyType

Field type for CentPrecisionMoney values.

name
String
"Money"

CustomFieldDateType

Field type for Date values.

name
String
"Date"

CustomFieldTimeType

Field type for Time values.

name
String
"Time"

CustomFieldDateTimeType

Field type for DateTime values.

name
String
"DateTime"

CustomFieldReferenceType

Field type for Reference values.

name
String
"Reference"
referenceTypeId

Resource type the Custom Field can reference.

CustomFieldSetType

Values of a SetType Custom Field are sets of values of the specified elementType (without duplicate elements).

name
String
"Set"
elementType

Field type of the elements in the set.

CustomFieldEnumValue

Defines an allowed value of a CustomFieldEnumType field.

key
String

Key of the value used as a programmatic identifier.

label
String

Descriptive label of the value.

CustomFieldLocalizedEnumValue

Defines an allowed value of a CustomFieldLocalizedEnumType field.

key
String

Key of the value used as a programmatic identifier.

label

Descriptive localized label of the value.

CustomFieldReferenceValue

Defines which resource type a CustomFieldReferenceType can reference.

cart

Cart

category

Category

channel

Channel

customer

Customer

key-value-document

CustomObject

order

Order

product

Product

product-type

ProductType

review

Review

state

State

shipping-method

ShippingMethod

zone

Zone

Get Type

Get Type by ID

GET
https://api.{region}.commercetools.com/{projectKey}/types/{id}
OAuth 2.0 Scopes:
view_types:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Type.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Type

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/types/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get Type by Key

GET
https://api.{region}.commercetools.com/{projectKey}/types/key={key}
OAuth 2.0 Scopes:
view_types:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Type.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Type

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/types/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Types

GET
https://api.{region}.commercetools.com/{projectKey}/types
OAuth 2.0 Scopes:
view_types:{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:

200TypePagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/types -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Type

POST
https://api.{region}.commercetools.com/{projectKey}/types
OAuth 2.0 Scopes:
manage_types:{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:TypeDraft
Response:

201Type

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/types -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "lineitemtype",
"name" : {
"en" : "lineitem"
},
"description" : {
"en" : "description"
},
"resourceTypeIds" : [ "line-item" ],
"fieldDefinitions" : [ {
"name" : "offer_name",
"label" : {
"en" : "offer_name"
},
"required" : false,
"type" : {
"name" : "String"
},
"inputHint" : "SingleLine"
} ]
}
DATA

Update Type

Update Type by ID

POST
https://api.{region}.commercetools.com/{projectKey}/types/{id}
OAuth 2.0 Scopes:
manage_types:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Type.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the 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 TypeUpdateAction

Update actions to be performed on the Type.

Response:

200Type

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/types/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA

Update Type by Key

POST
https://api.{region}.commercetools.com/{projectKey}/types/key={key}
OAuth 2.0 Scopes:
manage_types:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Type.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the 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 TypeUpdateAction

Update actions to be performed on the Type.

Response:

200Type

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/types/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "changeName",
"name" : {
"en" : "New Name"
}
} ]
}
DATA

Update actions

Change Key

key
String

New value to set. Must not be empty.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
action
String
"changeKey"
Example: json
{
"action" : "changeKey",
"key" : "NewKey"
}

Change Name

action
String
"changeName"
name

New value to set. Must not be empty.

Example: json
{
"action" : "changeName",
"name" : {
"en" : "NameDE",
"de" : "NameEN"
}
}

Set Description

action
String
"setDescription"
description

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

Example: json
{
"action" : "setDescription",
"description" : {
"de" : "DescriptionDE",
"en" : "DescriptionEN"
}
}

Add FieldDefinition

action
String
"addFieldDefinition"
fieldDefinition

Value to append to the array.

Example: json
{
"action" : "addFieldDefinition",
"fieldDefinition" : {
"type" : {
"name" : "LocalizedString"
},
"name" : "fieldDefinitionName",
"label" : {
"de" : "labelDE",
"en" : "labelEN"
},
"required" : false,
"inputHint" : "MultiLine"
}
}

Remove FieldDefinition

action
String
"removeFieldDefinition"
fieldName
String

name of the FieldDefinition to remove. The removal of a FieldDefinition deletes asynchronously all Custom Fields using the FieldDefinition as well.

Example: json
{
"action" : "removeFieldDefinition",
"fieldName" : "fieldDefinitionName"
}

Change FieldDefinition Label

action
String
"changeLabel"
fieldName
String

Name of the Field Definition to update.

label
Example: json
{
"action" : "changeLabel",
"fieldName" : "CustomTextField",
"label" : {
"de" : "NewLabelDE",
"en" : "NewLabelEN"
}
}

Add EnumValue to FieldDefinition

Adds a value to an EnumType. This update action can be used to update an EnumType FieldDefinition and a SetType FieldDefinition of EnumType.

action
String
"addEnumValue"
fieldName
String

name of the Field Definition to update.

value

Value to append to the array.

Example: json
{
"action" : "addEnumValue",
"fieldName" : "CustomENumField",
"value" : {
"key" : "NewENumKey",
"label" : "NewENumLabel"
}
}

Add LocalizedEnumValue to FieldDefinition

Adds a value to a LocalizedEnumType. This update action can be used to update a LocalizedEnumType FieldDefinition and a SetType FieldDefinition of CustomFieldLocalizedEnumType.

action
String
"addLocalizedEnumValue"
fieldName
String

name of the FieldDefinition to update.

value

Value to append to the array.

Example: json
{
"action" : "addLocalizedEnumValue",
"fieldName" : "CustomLeNumField",
"value" : {
"key" : "NewLocalizedEnumKeyString",
"label" : {
"en" : "NewLocalizedEnumLabelEN",
"de" : "NewLocalizedEnumLabelDE"
}
}
}

Change the order of FieldDefinitions

action
String
"changeFieldDefinitionOrder"
fieldNames
Array of String

Must match the set of names of FieldDefinitions (up to order).

Example: json
{
"action" : "changeFieldDefinitionOrder",
"fieldNames" : [ "CustomENumField", "CustomLeNumField", "CustomTextField" ]
}

Change the order of EnumValues

Changes the order of EnumValues in an EnumType FieldDefinition. This update action can be used to update an EnumType FieldDefinition and a SetType FieldDefinition of EnumType.

action
String
"changeEnumValueOrder"
fieldName
String

name of the FieldDefinition to update.

keys
Array of String

Must match the set of keys of the EnumValues in the FieldDefinition (apart from their order).

Example: json
{
"action" : "changeEnumValueOrder",
"fieldName" : "CustomENumField",
"keys" : [ "neweNumKey", "NewENumKey", "enum2", "enum1" ]
}

Change the order of LocalizedEnumValues

Changes the order of LocalizedEnumValues in a LocalizedEnumType FieldDefinition. This update action can be used to update a LocalizedEnumType FieldDefinition and a SetType of LocalizedEnumType FieldDefinitions.

action
String
"changeLocalizedEnumValueOrder"
fieldName
String

name of the Field Definition to update.

keys
Array of String

Must match the set of keys of the LocalizedEnumValues in the FieldDefinition (up to order).

Example: json
{
"action" : "changeLocalizedEnumValueOrder",
"fieldName" : "CustomLeNumField",
"keys" : [ "newleNumKey", "NewLocalizedEnumKeyString", "lenum2", "lenum1" ]
}

Change InputHint

action
String
"changeInputHint"
fieldName
String

name of the Field Definition to update.

inputHint

New value to set. Must not be empty.

Change EnumValue Label

Changes the label of an EnumValue of an EnumType FieldDefinition.

action
String
"changeEnumValueLabel"
fieldName
String

name of the FieldDefinition to update.

value

New value to set. Must not be empty.

Change LocalizedEnumValue Label

Changes the label of a LocalizedEnumValue of a LocalizedEnumType FieldDefinition.

action
String
"changeLocalizedEnumValueLabel"
fieldName
String

name of the FieldDefinition to update.

value

New value to set. Must not be empty.

Delete Type

These requests delete Types only if they are not referenced by other entities.

Delete Type by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/types/{id}
OAuth 2.0 Scopes:
manage_types:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Type.

Query parameters:
expand
The parameter can be passed multiple times.
version
Int

Last seen version of the resource.

Response:

200Type

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

Delete Type by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/types/key={key}
OAuth 2.0 Scopes:
manage_types:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Type.

Query parameters:
expand
The parameter can be passed multiple times.
version
Int

Last seen version of the resource.

Response:

200Type

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