Custom Fields

With custom fields, enhance the resources as you need.

The commercetools platform provides a flexible data model that covers a wide range of use cases. However, there might be use cases in which you wish to customize some resources in a way they fit your data model as close as possible.
With custom fields we give you the possibility to add fields to predefined resources, similar to AttributeDefinitions on ProductTypes. Please have a look at the resources that can currently be customized.

Before you can use a custom field on a resource you need to define the Type of the custom field you desire.
After the type definition you can set/read/update/delete the Custom field of the respective resources.

Customizable Resources

The following resources can be enhanced using CustomFields:

ResourceResource type id
Asset on Category and Product Variantasset
Categorycategory
Channelchannel
Customercustomer
CustomerGroupcustomer-group
Cartorder (same as Order)
CartDiscountcart-discount
DiscountCodediscount-code
InventoryEntryinventory-entry
Orderorder
OrderEditorder-edit
LineItem on Cart and Order, and LineItem on ShoppingListline-item
CustomLineItem on Cart and Ordercustom-line-item
Price on Product Variantproduct-price
Paymentpayment
InterfaceInteraction on Paymentpayment-interface-interaction
ShoppingListshopping-list
TextLineItem on ShoppingListshopping-list-text-line-item
Storestore
Reviewreview

When a Cart is ordered, the CustomFields are copied to the Order. Therefore the Custom Type for Orders is also valid for Carts.

On the tutorial page you can find some instructions about the use of Custom Types and CustomFields.

Representations

Custom

CustomFields

When using custom fields with GraphQL API mutations, you must escape any strings in the value field: "value" : "\"A value\"".

CustomFieldsDraft

The representation to be sent to the server when creating a resource with custom fields.

For example, if you create the following Type:

{
"key": "my-category",
"name": { "en": "customized fields" },
"description": { "en": "customized fields definition" },
"resourceTypeIds": ["category"],
"fieldDefinitions": [
{
"name": "description",
"type": { "name": "String" },
"required": true,
"label": { "en": "size" },
"inputHint": "SingleLine"
},
{
"name": "color",
"type": { "name": "String" },
"required": false,
"label": { "en": "color" },
"inputHint": "SingleLine"
}
]
}

you can use the following JSON to set the CustomFields when creating a Category:

{
[...]
"custom": {
"type": {
"key": "my-category"
},
"fields": {
"description": "example description"
}
}
}

In response to the request before the created category contains the following custom fields:

{
[...]
"custom": {
"type": {
"typeId": "type",
"id": "<type-id>"
},
"fields": {
"description": "example description"
}
}
}

Query for CustomFields

You can query categories, for example, with the following predicate that filters for categories with the CustomField "description" that have the value "example description": custom(fields(description="example description"))

Update CustomFields

Every customizable resource offers an update action for overwriting or unsetting the value of each custom field. The resource-specific fields of that update action are documented on the respective page for the customizable resource, but the common value is documented below.

Value

The FieldDefinition determines the format for the value to be provided: