Types

Elevate, May 20-22-2025, Miami Beach, Florida

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.

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.

Representations

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​

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.

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

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​

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.

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​Minimum: 0​Maximum: 500​
offset​
Int​

Number of elements skipped.

Default: 0​Maximum: 10000​
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​
type

Type of referenced resource.

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

Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

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​

A human-readable label for the field.

required​
Boolean​

Defines whether the field is required to have a value.

inputHint​

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.

FieldType

Abstract parent type for the specific field types with the common name field.

Some FieldTypes have additional fields for metadata. 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​
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​

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​

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​

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
​​
The parameter can be passed multiple times.
Response:
200

Type

asapplication/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
​​
The parameter can be passed multiple times.
Response:
200

Type

asapplication/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
​​
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
​

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

TypePagedQueryResponse

asapplication/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
​​

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
​​
The parameter can be passed multiple times.
Request Body:TypeDraftasapplication/json
Response:
201

Type

asapplication/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
​​
The parameter can be passed multiple times.
Request Body:TypeUpdateasapplication/json
Response:
200

Type

asapplication/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
​​
The parameter can be passed multiple times.
Request Body:TypeUpdateasapplication/json
Response:
200

Type

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

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​

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

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​

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​

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​

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​

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 names 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 keys 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 keys of the LocalizedEnumValues in the FieldDefinition (up to order).

Example: json
{
  "action": "changeLocalizedEnumValueOrder",
  "fieldName": "exampleLocalizedEnumField",
  "keys": [
    "lenum3",
    "lenum4",
    "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.

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​

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​

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
​​
The parameter can be passed multiple times.
Response:
200

Type

asapplication/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
​​
The parameter can be passed multiple times.
Response:
200

Type

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