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.

To get notified when the Custom Fields on a resource are updated, create a ChangeSubscription that subscribes to changes on that resource (for example, to Customer).

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` TypeReference	Reference to the Type that holds the FieldDefinitions for the Custom Fields.
`fields` FieldContainer	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` TypeResourceIdentifier	`id` or `key` of the Type.
`fields` FieldContainer	Object containing the Custom Fields for the customized resource or data type.

FieldContainer

JSON object containing name-value pairs with

name being the name of the Custom Field as defined in the respective FieldDefinition and
value being a CustomFieldValue compliant to the respective FieldType.

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 type	Data type
CustomFieldBooleanType	Boolean (`true` or `false`)
CustomFieldNumberType	Number
CustomFieldStringType	String
CustomFieldLocalizedStringType	LocalizedString
CustomFieldEnumType	String. Must be a `key` of one of the EnumValues defined in the EnumType
CustomFieldLocalizedEnumType	String. Must be a `key` of one of the LocalizedEnumValues defined in the LocalizedEnumType
CustomFieldMoneyType	CentPrecisionMoney
CustomFieldDateType	Date
CustomFieldTimeType	Time
CustomFieldDateTimeType	DateTime
CustomFieldReferenceType	Reference
CustomFieldSetType	JSON 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.