Custom Fields

This page documents the value representations of your self-defined project-specific fields, called Custom Fields, which you have on resources and data types that you have customized using Types.

These Custom Fields can be set or unset

  • with the resource or object draft during creation of a customizable data type, or
  • with Set CustomField update actions provided for each customizable data type.

Find the documentation for the drafts and the update actions in the respective API reference docs for the customized resource or data type.

Custom Fields are queryable and sortable.

Find a step-by-step example on how to use Types and Custom Fields in our respective tutorial.

Representations

CustomFields

When using Custom Fields with GraphQL API mutations, you must stringify all values in the value field: "value" : "\"A string value\"". The value field exists only in the GraphQL API, and not in the HTTP API.

Serves as value of the custom field on a resource or data type customized with a Type.

type

Reference to the Type that holds the FieldDefinitions for the Custom Fields.

fields

Object containing the Custom Fields for the customized resource or data type.

CustomFieldsDraft

The representation used when creating or updating a customizable data type with Custom Fields.

type

id or key of the Type.

fields

Object containing the Custom Fields for the customized resource or data type.

FieldContainer

JSON object containing name-value pairs with

Find below an example FieldContainer with CustomFieldValues of several FieldTypes:

{
"example-boolean-field": true,
"example-set-of-boolean-field": [true, false, true],
"example-string-field": "Any String value",
"example-set-of-string-field": ["Some String value", "Another String value"],
"example-localized-string-field": {
"en": "English text",
"es": "texto en español"
},
"example-set-of-localized-string-field": [
{
"en": "English text 1",
"es": "texto en español 1"
},
{
"en": "English text 2",
"es": "texto en español 2"
}
],
"example-enum-field": "enum key defined in FieldDefinition",
"example-set-of-enum-field": [
"enum key defined in FieldDefinition-1",
"enum key defined in FieldDefinition-2"
],
"example-localized-enum-field": "enum key defined in FieldDefinition",
"example-set-of-localized-enum-field": [
"enum key defined in FieldDefinition-1",
"enum key defined in FieldDefinition-2"
],
"example-number-field": 42,
"example-set-of-number-field": [1, 2, 7],
"example-money-field": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 124500,
"fractionDigits": 2
},
"example-set-of-money-field": [
{
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 124500,
"fractionDigits": 2
},
{
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 1000,
"fractionDigits": 2
}
],
"example-date-field": "2001-10-12",
"example-set-of-date-field": ["2001-10-12", "2015-03-14", "2003-05-15"],
"example-time-field": "14:00:00.000",
"example-set-of-time-field": ["14:00:00.000", "14:30:00.000"],
"example-datetime-field": "2018-10-14T14:00:00.000Z",
"example-set-of-datetime-field": ["2018-10-14T14:00:00.000Z"],
"example-reference-field": {
"typeId": "product",
"id": "d1229e6f-2b79-441e-b419-180311e52754"
},
"example-set-of-reference-field": [
{
"typeId": "product",
"id": "d1229e6f-2b79-441e-b419-180311e52754"
},
{
"typeId": "customer",
"id": "e1549e6f-3b79-441e-c486-957480r23744"
}
]
}

CustomFieldValue

The value of a Custom Field. The data type of the value depends on the specific FieldType given in the type field of the FieldDefinition for a Custom Field. It can be any of the following:

Field typeData type
CustomFieldBooleanTypeBoolean (true or false)
CustomFieldNumberTypeNumber
CustomFieldStringTypeString
CustomFieldLocalizedStringTypeLocalizedString
CustomFieldEnumTypeString. Must be a key of one of the EnumValues defined in the EnumType
CustomFieldLocalizedEnumTypeString. Must be a key of one of the LocalizedEnumValues defined in the LocalizedEnumType
CustomFieldMoneyTypeCentPrecisionMoney
CustomFieldDateTypeDate
CustomFieldTimeTypeTime
CustomFieldDateTimeTypeDateTime
CustomFieldReferenceTypeReference
CustomFieldSetTypeJSON array without duplicates consisting of CustomFieldValues of a single FieldType. For example, a Custom Field of CustomFieldSetType of CustomFieldDateType takes a JSON array of mutually different Dates for its value. The order of items in the array is not fixed. For more examples, see the example FieldContainer.