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 uses 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

Please find attached the currently supported resources which can be enhanced using CustomFields.

ResourceResource type id
Assetasset
Categoriescategory
Channelschannel
Customerscustomer
Carts order (same as Orders)
InventoryEntryinventory-entry
Ordersorder
LineItems on Carts, Orders
& ShoppingLists
line-item
CustomLineItemscustom-line-item
ProductPriceproduct-price
Paymentpayment
Payment InterfaceInteractionpayment-interface-interaction
ShoppingListshopping-list
ShoppingList TextLineItemshopping-list-text-line-item
Reviewsreview

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

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

Representations

Custom

CustomFields

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": "my description"
    }
  }
}

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

{
  [...]
  "custom": {
    "type": {
      "typeId": "type",
      "id": "<type-id>"
    },
    "fields": {
      "description": "my 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 “my description”: custom(fields(description="my description"))