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:

Resource	Resource type id
Address on Cart, Order, OrderEdit, Customer, and Channel	`address`
Asset on Category and Product Variant	`asset`
Cart	`order` (same as Order)
CartDiscount	`cart-discount`
Category	`category`
Channel	`channel`
Customer	`customer`
CustomerGroup	`customer-group`
CustomLineItem on Cart and Order	`custom-line-item`
Delivery	`order-delivery`
Parcel	`order-delivery`
DiscountCode	`discount-code`
InterfaceInteraction on Payment	`payment-interface-interaction`
InventoryEntry	`inventory-entry`
LineItem on Cart and Order, and LineItem on ShoppingList	`line-item`
Order	`order`
ReturnItem	`order`
OrderEdit	`order-edit`
Payment	`payment`
Price on Product Variant	`product-price`
Review	`review`
ShippingMethod	`shipping-method`
ShoppingList	`shopping-list`
Store	`store`
TextLineItem on ShoppingList	`shopping-list-text-line-item`
Transaction on Payment	`transaction`

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

custom - CustomFields

CustomFields

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

type - Reference to the Type.
fields - FieldContainer

CustomFieldsDraft

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

type - ResourceIdentifier of a Type - Required
The id or the key of the type to use.
fields - FieldContainer - Optional

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

FieldContainer

A valid JSON object based on the FieldDefinition of Type.

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"))

It is also possible to sort Custom Fields using custom.fields.${fieldName} sort parameter.

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:

for EnumType and LocalizedEnumType fields: the key of the EnumValue or the LocalizedEnumValue
for LocalizedStringType fields: the LocalizedString object
for MoneyType fields: the Money object
for SetType fields: the entire Set object
for ReferenceType fields: the Reference object