# Custom Fields

Set values for Custom Fields defined by [Types](/api/projects/types.md).

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](/api/projects/types.md).

Custom Fields can be set or unset

- with the resource or object draft during creation of a [customizable data type](/api/projects/types.md#resourcetypeid), or
- with Set CustomField update actions provided for each [customizable data type](/api/projects/types.md#resourcetypeid).

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](/api/predicates/query.md) and [sortable](/api/general-concepts.md#sorting). [ReferenceType](/api/projects/types.md#customfieldreferencetype) Custom Fields are [expandable](/api/general-concepts.md#reference-expansion).

To get notified when the Custom Fields on a resource are updated, create a [ChangeSubscription](/urn?urn=ctp%3Aapi%3Atype%3AChangeSubscription) that subscribes to changes on that resource (for example, to `Customer`).

Find a step-by-step example on how to use [Types](/api/projects/types.md) and Custom Fields in our respective [tutorial](/tutorials/custom-types.md).

## Representations

### CustomFields

When using Custom Fields with [GraphQL API](/api/graphql.md) 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.

[type definition](/api/projects/custom-fields.md?urn=ctp:api:type:CustomFields).

### CustomFieldsDraft

[type definition](/api/projects/custom-fields.md?urn=ctp:api:type:CustomFieldsDraft).

### FieldContainer

A JSON object containing key-value pairs.

- key is the `name` of the Custom Field, as defined in the respective [FieldDefinition](/urn?urn=ctp%3Aapi%3Atype%3AFieldDefinition).
- value is the [CustomFieldValue](/api/projects/custom-fields.md#customfieldvalue) compliant to the respective [FieldType](/urn?urn=ctp%3Aapi%3Atype%3AFieldType).

Find below an example FieldContainer with CustomFieldValues of several FieldTypes:

```json
{
  "exampleBooleanField": true,
  "exampleSetOfBooleanField": [true, false, true],
  "exampleStringField": "Any String value",
  "exampleSetOfStringField": ["Some String value", "Another String value"],
  "exampleLocalizedStringField": {
    "en": "English text",
    "es": "texto en español"
  },
  "exampleSetOfLocalizedStringField": [
    {
      "en": "English text 1",
      "es": "texto en español 1"
    },
    {
      "en": "English text 2",
      "es": "texto en español 2"
    }
  ],
  "exampleEnumField": "enum key defined in FieldDefinition",
  "exampleSetOfEnumField": [
    "enum key defined in FieldDefinition-1",
    "enum key defined in FieldDefinition-2"
  ],
  "exampleLocalizedEnumField": "enum key defined in FieldDefinition",
  "exampleSetOfLocalizedEnumField": [
    "enum key defined in FieldDefinition-1",
    "enum key defined in FieldDefinition-2"
  ],
  "exampleNumberField": 42,
  "exampleSetOfNumberField": [1, 2, 7],
  "exampleMoneyField": {
    "type": "centPrecision",
    "currencyCode": "USD",
    "centAmount": 124500,
    "fractionDigits": 2
  },
  "exampleSetOfMoneyField": [
    {
      "type": "centPrecision",
      "currencyCode": "USD",
      "centAmount": 124500,
      "fractionDigits": 2
    },
    {
      "type": "centPrecision",
      "currencyCode": "USD",
      "centAmount": 1000,
      "fractionDigits": 2
    }
  ],
  "exampleDateField": "2001-10-12",
  "exampleSetOfDateField": ["2001-10-12", "2015-03-14", "2003-05-15"],
  "exampleTimeField": "14:00:00.000",
  "exampleSetOfTimeField": ["14:00:00.000", "14:30:00.000"],
  "exampleDatetimeField": "2018-10-14T14:00:00.000Z",
  "exampleSetOfDatetimeField": ["2018-10-14T14:00:00.000Z"],
  "exampleReferenceField": {
    "typeId": "product",
    "id": "d1229e6f-2b79-441e-b419-180311e52754"
  },
  "exampleSetOfReferenceField": [
    {
      "typeId": "product",
      "id": "d1229e6f-2b79-441e-b419-180311e52754"
    },
    {
      "typeId": "product",
      "id": "e1549e6f-3b79-441e-c486-957480r23744"
    }
  ]
}
```

### CustomFieldValue

The value of a Custom Field.

The data type of the value depends on the specific [FieldType](/urn?urn=ctp%3Aapi%3Atype%3AFieldType) given in the `type` field of the [FieldDefinition](/urn?urn=ctp%3Aapi%3Atype%3AFieldDefinition) for a Custom Field.
It can be any of the following:

| Field type | Data type |
| --- | --- |
| [CustomFieldBooleanType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldBooleanType) | Boolean (`true` or `false`) |
| [CustomFieldNumberType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldNumberType) | Number |
| [CustomFieldStringType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldStringType) | String |
| [CustomFieldLocalizedStringType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldLocalizedStringType) | [LocalizedString](/api/types.md#localizedstring) |
| [CustomFieldEnumType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldEnumType) | String. Must be a `key` of one of the [EnumValues](/api/projects/types.md#customfieldenumvalue) defined in the [EnumType](/api/projects/types.md#customfieldenumtype) |
| [CustomFieldLocalizedEnumType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldLocalizedEnumType) | String. Must be a `key` of one of the [LocalizedEnumValues](/api/projects/types.md#customfieldlocalizedenumvalue) defined in the [LocalizedEnumType](/api/projects/types.md#customfieldlocalizedenumtype) |
| [CustomFieldMoneyType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldMoneyType) | [CentPrecisionMoney](/api/types.md#centprecisionmoney) |
| [CustomFieldDateType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldDateType) | [Date](/api/types.md#date) |
| [CustomFieldTimeType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldTimeType) | [Time](/api/types.md#time) |
| [CustomFieldDateTimeType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldDateTimeType) | [DateTime](/api/types.md#datetime) |
| [CustomFieldReferenceType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldReferenceType) | [Reference](/urn?urn=ctp%3Aapi%3Atype%3AReference) identified by `id` only. Does not support [KeyReference](/urn?urn=ctp%3Aapi%3Atype%3AKeyReference). |
| [CustomFieldSetType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldSetType) | JSON array without duplicates consisting of [CustomFieldValues](/api/projects/custom-fields.md#customfieldvalue) of a single [FieldType](/urn?urn=ctp%3Aapi%3Atype%3AFieldType). 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](/api/projects/custom-fields.md#fieldcontainer). |

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Types](/api/projects/types.md)
- [Next page: Custom Objects](/api/projects/custom-objects.md)