Types

Define Project-specific Custom Fields on resources and data types.

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 these data types.

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

FieldDefinition is similar to 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 values of Custom Fields are represented by CustomFieldValue on Custom Fields.

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

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: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` LocalizedString	Name of the Type.
`description` LocalizedString	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.
`createdAt` DateTime	Date and time (UTC) the Type was initially created.
`createdBy`BETA CreatedBy	IDs and references that created the Type.
`lastModifiedAt` DateTime	Date and time (UTC) the Type was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the Type.

TypeDraft

`key` String	User-defined unique identifier for the Type. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`name` LocalizedString	Name of the Type.
`description` LocalizedString	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.

Example: json

{
  "key": "line-item-string-field",
  "name": {
    "en": "String Custom Field on Line Items"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ]
}

TypePagedQueryResponse

PagedQueryResult with results containing an array of Types.

`limit` Int	Number of results requested. Default: `20`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10 000`
`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

Reference to a Type.

`id` String	Unique identifier of the referenced Type.
`typeId` ReferenceTypeId	`"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

ResourceIdentifier of a Type. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

`id` String	Unique identifier of the referenced Type. Required if `key` is absent.
`key` String	User-defined unique identifier of the referenced Type. Required if `id` is absent. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`typeId` ReferenceTypeId	`"type"` References a Type.

ResourceTypeId

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

address: Address on BusinessUnit, Cart, Order, OrderEdit, Customer, and Channel
asset: Asset on Category and ProductVariant
approval-flow: ApprovalFlow
approval-rule: ApprovalRule
associate-role: AssociateRole
business-unit: BusinessUnit
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 Carts are also valid for Orders, and hence both have the same identifier: order.
order-edit: OrderEdit
order-delivery: Delivery
order-parcel: Parcel
order-return-item: ReturnItem
payment: Payment
payment-interface-interaction: InterfaceInteraction on Payment
product-price: Embedded Price on ProductVariant
product-selection: ProductSelection
product-tailoring: ProductTailoring
quote: Quote, QuoteRequest and StagedQuote. When a StagedQuote is created, the CustomFields will be copied from the QuoteRequest and when a Quote is created, the CustomFields will be copied from the StagedQuote. For this reason, the Types for Quotes are also valid for QuoteRequests and StagedQuotes, and hence all have the same identifier: quote.
review: Review
shipping: Shipping
shipping-method: ShippingMethod
shopping-list: ShoppingList
shopping-list-text-line-item: TextLineItem on ShoppingList
standalone-price: StandalonePrice
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` FieldType	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: `2`MaxLength: `36`Pattern: `^[A-Za-z0-9_-]+$`
`label` LocalizedString	A human-readable label for the field.
`required` Boolean	Defines whether the field is required to have a value.
`inputHint` TypeTextInputHint	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. Default: `SingleLine`

Example: json

{
  "type": {
    "name": "Set",
    "elementType": {
      "name": "Reference",
      "referenceTypeId": "product"
    }
  },
  "name": "exampleSetOfReferenceField",
  "label": {
    "en": "Example Set of Reference Field"
  },
  "required": false,
  "inputHint": "SingleLine"
}

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.

`name` String	`"Enum"`
`values` Array of CustomFieldEnumValue	Allowed values.

Example: json

{
  "name": "Enum",
  "values": [
    {
      "key": "first-value",
      "label": "First"
    },
    {
      "key": "second-value",
      "label": "Second"
    }
  ]
}

CustomFieldLocalizedEnumType

Field type for localized enum values.

`name` String	`"LocalizedEnum"`
`values` Array of CustomFieldLocalizedEnumValue	Allowed values.

Example: json

{
  "name": "LocalizedEnum",
  "values": [
    {
      "key": "first-value",
      "label": {
        "en": "First",
        "de": "Erste"
      }
    },
    {
      "key": "second-value",
      "label": {
        "en": "Second",
        "de": "Zweite"
      }
    }
  ]
}

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` CustomFieldReferenceValue	Resource type the Custom Field can reference.

Example: json

{
  "name": "Reference",
  "referenceTypeId": "product"
}

CustomFieldSetType

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

`name` String	`"Set"`
`elementType` FieldType	Field type of the elements in the set.

Example: json

{
  "name": "Set",
  "elementType": {
    "name": "Reference",
    "referenceTypeId": "product"
  }
}

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.

Example: json

{
  "key": "enum-value-key",
  "label": "Enum value label"
}

CustomFieldLocalizedEnumValue

Defines an allowed value of a CustomFieldLocalizedEnumType field.

`key` String	Key of the value used as a programmatic identifier.
`label` LocalizedString	Descriptive localized label of the value.

Example: json

{
  "key": "localized-enum-value-key",
  "label": {
    "en": "Localized enum value label"
  }
}

CustomFieldReferenceValue

Defines which resource type a CustomFieldReferenceType can reference.

approval-flow: ApprovalFlow
approval-rule: ApprovalRule
associate-role: AssociateRole
business-unit: BusinessUnit
cart: Cart
cart-discount: CartDiscount
category: Category
channel: Channel
customer: Customer
customer-group: CustomerGroup
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

Expansion

The parameter can be passed multiple times.

Response:

200Typeasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/types/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 1,
  "key": "line-item-string-field",
  "name": {
    "en": "String Custom Field on Line Items"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2023-10-07T06:56:19.217Z"
}

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

Expansion

The parameter can be passed multiple times.

Response:

200Typeasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/types/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 1,
  "key": "line-item-string-field",
  "name": {
    "en": "String Custom Field on Line Items"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2023-10-07T06:56:19.217Z"
}

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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed. Default: `true`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200TypePagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/types -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: TypePagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
      "version": 1,
      "key": "line-item-string-field",
      "name": {
        "en": "String Custom Field on Line Items"
      },
      "description": {
        "en": "This adds a Custom Field on Line Items, which can hold any string value."
      },
      "resourceTypeIds": ["line-item"],
      "fieldDefinitions": [
        {
          "name": "exampleStringField",
          "label": {
            "en": "Example string field."
          },
          "required": false,
          "type": {
            "name": "String"
          },
          "inputHint": "SingleLine"
        }
      ],
      "createdAt": "2023-10-07T06:56:19.217Z",
      "lastModifiedAt": "2023-10-07T06:56:19.217Z"
    }
  ]
}

Check if Type exists

Check if Type exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/types/{id}

Checks if a Type exists for a given id. Returns a 200 OK status if the Type exists or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/types/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Type exists by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/types/key={key}

Checks if a Type exists for a given key. Returns a 200 OK status if the Type exists or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/types/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Type exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/types

Checks if a Type exists for a given Query Predicate. Returns a 200 OK status if any Types match the Query Predicate or a 404 Not Found otherwise.

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

QueryPredicate

Query Predicates on Types are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

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

Expansion

The parameter can be passed multiple times.

Request Body:TypeDraftasapplication/json

Response:

201Typeasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/types -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "line-item-string-field",
  "name" : {
    "en" : "String Custom Field on Line Items"
  },
  "description" : {
    "en" : "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds" : [ "line-item" ],
  "fieldDefinitions" : [ {
    "name" : "exampleStringField",
    "label" : {
      "en" : "Example string field."
    },
    "required" : false,
    "type" : {
      "name" : "String"
    },
    "inputHint" : "SingleLine"
  } ]
}
DATA

201 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 1,
  "key": "line-item-string-field",
  "name": {
    "en": "String Custom Field on Line Items"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2023-10-07T06:56:19.217Z"
}

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

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`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 ConcurrentModification error will be returned.
`actions` Array of TypeUpdateAction	Update actions to be performed on the Type.

Response:

200Typeasapplication/json

Request Example:cURL

curl 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

200 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 2,
  "key": "line-item-string-field",
  "name": {
    "en": "New Name"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2024-08-06T13:49:48.511Z"
}

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

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`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 ConcurrentModification error will be returned.
`actions` Array of TypeUpdateAction	Update actions to be performed on the Type.

Response:

200Typeasapplication/json

Request Example:cURL

curl 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

200 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 2,
  "key": "line-item-string-field",
  "name": {
    "en": "New Name"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2024-08-06T13:49:48.511Z"
}

Update actions

Remove FieldDefinition

Change FieldDefinition Label

Add EnumValue to FieldDefinition

Add LocalizedEnumValue to FieldDefinition

Change the order of FieldDefinitions

Change the order of EnumValues

Change the order of LocalizedEnumValues

Change InputHint

Change EnumValue Label

Change LocalizedEnumValue Label

Change Key

`action` String	`"changeKey"`
`key` String	New value to set. Must not be empty. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "changeKey",
  "key": "NewKey"
}

Change Name

`action` String	`"changeName"`
`name` LocalizedString	New value to set. Must not be empty.

Example: json

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

Set Description

`action` String	`"setDescription"`
`description` LocalizedString	Value to set. If empty, any existing value will be removed.

Example: json

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

Add FieldDefinition

Defines a new field for a Type. Adding new required fields to a Type that is already referenced by existing entities can put those entities in a temporarily inconsistent state.

If a Type that is already in use requires new fields, we recommend making them optional (required set to false) whenever possible. Alternatively, any new required fields should be added one at a time followed by an update to all the resources using the Type. This prevents validation errors caused by an entity missing more than one required custom field.

`action` String	`"addFieldDefinition"`
`fieldDefinition` 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` LocalizedString	New value to set. Must not be empty.

Example: json

{
  "action": "changeLabel",
  "fieldName": "exampleStringField",
  "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` CustomFieldEnumValue	Value to append to the array.

Example: json

{
  "action": "addEnumValue",
  "fieldName": "exampleEnumField",
  "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` CustomFieldLocalizedEnumValue	Value to append to the array.

Example: json

{
  "action": "addLocalizedEnumValue",
  "fieldName": "exampleLocalizedEnumField",
  "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 `name`s of FieldDefinitions (up to order).

Example: json

{
  "action": "changeFieldDefinitionOrder",
  "fieldNames": [
    "exampleEnumField",
    "exampleLocalizedEnumField",
    "exampleStringField"
  ]
}

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 `key`s of the EnumValues in the FieldDefinition (apart from their order).

Example: json

{
  "action": "changeEnumValueOrder",
  "fieldName": "exampleEnumField",
  "keys": ["enum3", "enum4", "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 `key`s of the LocalizedEnumValues in the FieldDefinition (up to order).

Example: json

{
  "action": "changeLocalizedEnumValueOrder",
  "fieldName": "exampleLocalizedEnumField",
  "keys": ["lenum3", "lenum4", "lenum2", "lenum1"]
}

Change InputHint

Changes the inputHint of CustomFieldStringType FieldDefinition, a CustomFieldLocalizedStringType FieldDefinition, and CustomFieldSetType FieldDefinition of these string-based FieldTypes.

`action` String	`"changeInputHint"`
`fieldName` String	`name` of the Field Definition to update.
`inputHint` TypeTextInputHint	New value to set. Must not be empty.

Example: json

{
  "action": "changeInputHint",
  "fieldName": "exampleBooleanField",
  "inputHint": "MultiLine"
}

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` CustomFieldEnumValue	New value to set. Must not be empty.

Example: json

{
  "action": "changeEnumValueLabel",
  "fieldName": "exampleEnumField",
  "value": {
    "key": "NewENumKey",
    "label": "New value"
  }
}

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` CustomFieldLocalizedEnumValue	New value to set. Must not be empty.

Example: json

{
  "action": "changeLocalizedEnumValueLabel",
  "fieldName": "exampleLocalizedEnumField",
  "value": {
    "key": "NewLocalizedEnumKeyString",
    "label": {
      "en": "NewLocalizedEnumLabelEN",
      "de": "NewLocalizedEnumLabelDE"
    }
  }
}

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:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200Typeasapplication/json

Request Example:cURL

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

200 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 1,
  "key": "line-item-string-field",
  "name": {
    "en": "String Custom Field on Line Items"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2023-10-07T06:56:19.217Z"
}

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:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200Typeasapplication/json

Request Example:cURL

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

200 Response Example: Typejson

{
  "id": "ff8b0f8c-78c8-4c4c-a4b7-2545d9279515",
  "version": 1,
  "key": "line-item-string-field",
  "name": {
    "en": "String Custom Field on Line Items"
  },
  "description": {
    "en": "This adds a Custom Field on Line Items, which can hold any string value."
  },
  "resourceTypeIds": ["line-item"],
  "fieldDefinitions": [
    {
      "name": "exampleStringField",
      "label": {
        "en": "Example string field."
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ],
  "createdAt": "2023-10-07T06:56:19.217Z",
  "lastModifiedAt": "2023-10-07T06:56:19.217Z"
}

Types

Representations

Type

TypeDraft

TypePagedQueryResponse

TypeReference

TypeResourceIdentifier

ResourceTypeId

FieldDefinition

TextInputHint

FieldType

CustomFieldBooleanType

CustomFieldNumberType

CustomFieldStringType

CustomFieldLocalizedStringType

CustomFieldEnumType

CustomFieldLocalizedEnumType

CustomFieldMoneyType

CustomFieldDateType

CustomFieldTimeType

CustomFieldDateTimeType

CustomFieldReferenceType

CustomFieldSetType

CustomFieldEnumValue

CustomFieldLocalizedEnumValue

CustomFieldReferenceValue

Get Type

Get Type by ID

Get Type by Key

Query Types

Check if Type exists

Check if Type exists by ID

Check if Type exists by Key

Check if Type exists by Query Predicate

Create Type

Update Type

Update Type by ID

Update Type by Key

Update actions

Change Key

Change Name

Set Description

Add FieldDefinition

Remove FieldDefinition

Change FieldDefinition Label

Add EnumValue to FieldDefinition

Add LocalizedEnumValue to FieldDefinition

Change the order of FieldDefinitions

Change the order of EnumValues

Change the order of LocalizedEnumValues

Change InputHint

Change EnumValue Label

Change LocalizedEnumValue Label

Delete Type

Delete Type by ID

Delete Type by Key