Currency Custom Field

A currency custom field stores a monetary amount together with a currency code (1500.50 + USD) on a record. It maps to the CURRENCY value of the CustomFieldType enum. Records are Record objects and custom fields are CustomField objects in the API.

The set of currencies a field offers is stored as CustomFieldOption rows on the field — one option per currency (USD, EUR, GBP, …), each identified by its three-letter code in title. The field’s currency property is the default code used when a value omits one.

Overview

Create

Use the createCustomField mutation with type: CURRENCY. The field is created in the workspace identified by the blue-workspace-id header — there is no projectId argument. Set currency to the default code and, optionally, min/max to record an intended range.

mutation CreateCurrencyField {
  createCustomField(
    input: { name: "Deal Value", type: CURRENCY, currency: "USD", min: 0, max: 1000000 }
  ) {
    id
    name
    type
    currency
    min
    max
  }
}

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Deal Value",
      "type": "CURRENCY",
      "currency": "USD",
      "min": 0,
      "max": 1000000
    }
  }
}

CreateCustomFieldInput

Set a value

Use the setRecordCustomField mutation with number (the amount) and currency (the code). It returns Boolean! — there are no subfields to select.

mutation SetDealValue {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", number: 1500.50, currency: "USD" }
  )
}

{ "data": { "setRecordCustomField": true } }

SetRecordCustomFieldInput

Setting a value while creating a record

createRecord takes custom field values as CreateRecordInputCustomField entries, each with only customFieldId and a single value string — there is no separate currency key here. For a currency field, encode the amount and code into one string:

The code (when present) is matched against the field’s currency CustomFieldOption rows; an unrecognized code falls back to the field’s first option.

mutation CreateDeal {
  createRecord(
    input: {
      title: "Acme renewal"
      todoListId: "list_123"
      customFields: [{ customFieldId: "field_123", value: "25000.00GBP" }]
    }
  ) {
    id
    title
    customFields {
      name
      type
      number
      currency
    }
  }
}

{
  "data": {
    "createRecord": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Acme renewal",
      "customFields": [
        { "name": "Deal Value", "type": "CURRENCY", "number": 25000, "currency": "GBP" }
      ]
    }
  }
}

Read a value

Read currency values from a record’s customFields connection. Each element is a CustomField — select number for the amount and currency for the code.

query ReadDealValue {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], todoListIds: ["list_123"] }) {
      items {
        id
        title
        customFields {
          name
          type
          number
          currency
        }
      }
    }
  }
}

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "title": "Acme renewal",
            "customFields": [
              { "name": "Deal Value", "type": "CURRENCY", "number": 25000, "currency": "GBP" }
            ]
          }
        ]
      }
    }
  }
}

Notes

• Amount and code are separate columns. number holds the amount, currency holds the code. setRecordCustomField writes both directly; createRecord parses both out of the single value string.
• min/max are not enforced. They are stored on the field as a documented range but are not validated when values are set or updated.
• Conversion is a separate field type. A CURRENCY field does not convert between currencies. To convert a source amount into other currencies automatically, use a Currency Conversion field.

Errors

Related

• Currency Conversion field — automatic conversion using exchange rates.
• Number field — numeric values without a currency code.
• Formula field — calculations across numeric and currency fields.
• Set custom field values — setting values across all field types.
• Create a custom field — the full createCustomField reference.