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
Address on Cart, Order, OrderEdit, Customer, and Channeladdress
Asset on Category and Product Variantasset
Cartorder (same as Order)
CartDiscountcart-discount
Categorycategory
Channelchannel
Customercustomer
CustomerGroupcustomer-group
CustomLineItem on Cart and Ordercustom-line-item
DiscountCodediscount-code
InterfaceInteraction on Paymentpayment-interface-interaction
InventoryEntryinventory-entry
LineItem on Cart and Order, and LineItem on ShoppingListline-item
Orderorder
OrderEditorder-edit
Paymentpayment
Price on Product Variantproduct-price
Reviewreview
ShippingMethodshipping-method
ShoppingListshopping-list
Storestore
TextLineItem on ShoppingListshopping-list-text-line-item

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

  • custom - CustomFields

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

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

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:

Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2021 commercetools
Privacy PolicyImprint