ObjectStackObjectStack

Currency fields — dynamic, fixed and record modes

How a currency amount gets its currency — the tenant default, one fixed code, or each record's own ISO 4217 code in a sibling field — and the writes, aggregates and declarations the platform refuses for a record-currency amount

A currency field stores a bare number in every mode, never a { value, currency } object (ADR-0104 D1). What the field's currencyConfig decides is where that number's currency comes from. There are three modes, and the record mode is the one to use when different records of the same object are in different currencies: an invoice in USD next to an invoice in EUR (ADR-0144).

The three modes

currencyModeThe amount's currencyKeys it reads
dynamic (the default)The tenant default currency, the localization.currency setting. With no setting, the amount is a plain number with no symbol.none — defaultCurrency is not read
fixedOne currency for the whole column.defaultCurrency, required
recordEach record's own currency: the ISO 4217 code stored in a sibling field of the same record.currencyField, required
// dynamic: displays in the organization's currency
budget: Field.currency({ label: 'Budget' }),

// fixed: every row is in USD
list_price: Field.currency({
  label: 'List Price',
  currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' },
}),

// record: every row names its own currency in `currency_code`
amount: Field.currency({
  label: 'Amount',
  currencyConfig: { currencyMode: 'record', currencyField: 'currency_code' },
}),

Pick by asking what the currency belongs to. If it belongs to the organization, use dynamic. If it belongs to the column, such as a price list kept in one currency, use fixed. If it belongs to the document, such as an invoice billed in the customer's currency, use record.

The modes do not mix in one config. fixed needs its code and record needs its pointer. Nothing turns multi-currency on for an organization or a deployment: declaring currencyMode: 'record' on a field is the switch, and the field is the only place it applies.

The record mode

The code field

A record-mode amount names, through currencyConfig.currencyField, a field on the same object that holds each record's currency. That field must be a text field declaring valueDomain: 'iso_4217_currency', so every code written to it is checked against the ISO 4217 list.

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Invoice = ObjectSchema.create({
  name: 'invoice',
  label: 'Invoice',
  fields: {
    name: Field.text({ label: 'Number', required: true }),
    currency_code: Field.text({ label: 'Currency', valueDomain: 'iso_4217_currency' }),
    amount: Field.currency({
      label: 'Amount',
      currencyConfig: { currencyMode: 'record', currencyField: 'currency_code' },
    }),
    tax: Field.currency({
      label: 'Tax',
      currencyConfig: { currencyMode: 'record', currencyField: 'currency_code' },
    }),
  },
});

currency_code is a convention, not a contract. The platform never injects a code column and never looks one up by name: the code field is whatever field you declare and point at. Several amounts may share one code field, as amount and tax do above, and an object may carry two code fields when a record really holds amounts in two currencies.

A formula field with returnType: 'currency' that computes from record-mode amounts carries the same config, { currencyMode: 'record', currencyField: … }, naming the code field its source amounts name. inferFormulaReturn in @objectstack/formula answers it for a formula it can prove is money.

What the declaration refuses

ObjectSchema.create(), os validate and publish refuse each of these, with the fix in the message:

DeclarationRefused atFix
currencyMode: 'record' with no currencyFieldcurrencyConfig.currencyFieldName the code field, or use fixed (one currency) or dynamic (the tenant default).
currencyField under dynamic or fixedcurrencyConfig.currencyFieldSet currencyMode: 'record', or delete currencyField.
defaultCurrency under recordcurrencyConfig.defaultCurrencyDelete defaultCurrency, or use fixed if the field has one currency.
currencyField: ''currencyConfig.currencyFieldName a field.
currencyField names no other field of the object, or names the amount itselffields.<amount>.currencyConfig.currencyFieldPoint at a declared code field. The message lists the object's candidates.
currencyField names a field that is not textsamePoint at a text field.
currencyField names a text field without valueDomain: 'iso_4217_currency'sameAdd valueDomain: 'iso_4217_currency' to that field.

A master_detail child may follow its parent's currency instead, with the two-segment path currencyField: 'PARENT_FIELD.CODE_FIELD'. The object alone judges the first segment. The second names a field of the parent, so it is judged where both objects are known: defineStack refuses a path whose second segment is no field of the parent, or a field that does not hold an ISO 4217 code. On a running server, saving one of the two objects through the metadata API (PUT /meta/object/:name), or publishing its draft (POST /meta/object/:name/publish), with the other already registered is refused with INVALID_METADATA / 422 and the same message, whichever is saved second, and nothing is stored or published; a parent saved without the code field a registered child follows is refused the same way. A draft is judged when it is published. Objects registered while the server boots, or by a package install, are not judged this way.

Writing a record

When a record-mode amount holds a value, its code field must hold a code in the same write. An insert, or an update that leaves the amount beside a blank code (absent, null or white space only), is refused with ERR_CURRENCY_CODE_REQUIRED / 400 and nothing is written. The error names the code field in field and the amount in amountField. Fix it by writing the record's code, for example 'USD', in the same write, or by leaving the amount empty.

  • A blank amount needs no code.
  • On an update, only the amount and code pairs the payload touches are judged, so editing an unrelated field of an older row is not refused.
  • A code that is not an ISO 4217 code is refused by the code field's own valueDomain, not by this rule.

The platform never fills in a code. No server default, no tenant fallback and no "most recent currency" is ever stored on your behalf. In the Console, a create form opens with the code field pre-filled with the organization's currency, and the user submits it as an explicit value. A defaultValue you declare on the code field yourself is an ordinary field default: the engine applies it before the check, so it satisfies the rule, because you wrote it.

Switching a field that already holds rows

An existing dynamic or fixed amount can be switched to currencyMode: 'record', but every row already stored then holds an amount beside a blank code. Such a row is not refused for resting, but it shows as a plain number, falls into the null group of a grouped aggregate, and sits outside every filter on the pair until it holds a code.

  1. The save answers 409 destructive_change. Saving the switched object reports the finding currency_mode_to_record on the amount field, and the message names the command to run. Re-submit the save with force (?force=true on PUT /api/v1/meta/:type/:name) to make the switch.
  2. Dry run. os migrate record-currency-codes --object opportunity --field amount --code USD counts the rows holding an amount and no code, and writes nothing.
  3. --apply. The same command with --apply writes the code into those rows. It is idempotent: re-run it until the report says zero.

The code is the one you give with --code, and it is never derived: not from the defaultCurrency the field had under fixed, not from the organization's currency. One run writes one code, so if the stored amounts are in more than one currency, split those rows with your own writes first. Each organization has its own home currency, so on a database whose rows belong to more than one organization, run it once per organization with --org <id> and the code that organization's rows are in: a run naming no organization there is refused before any write and lists each organization's codeless row count, and --all-organizations writes the one code into every organization's rows when it really is right for all of them. See os migrate record-currency-codes. With no shell on the deployment (a hosted organization), an organization admin holding setup.write runs the same backfill for their current organization's rows with POST /api/v1/meta/_migrate-record-currency-codes and the body { "object", "field", "code", "apply" }, a preview unless apply is true.

Re-pointing currencyField on a field that already holds rows

The amount is a bare number, and its currency is whatever the field currencyField names holds. Pointing an existing record-mode amount at another field (another sibling, or a master_detail child's PARENT_FIELD.CODE_FIELD path, in either direction) converts no stored amount: every row keeps its number and is read in the currency the new field holds. A row whose old and new codes differ now displays, filters and groups under a currency it was not entered in.

  1. The save answers 409 destructive_change. Saving the re-pointed object reports the finding currency_field_repointed on the amount field. The save reads no row, so it reports the finding whether or not the table holds any. Re-submit with force (?force=true on PUT /api/v1/meta/:type/:name) to make the change. An identical pointer is not a re-point, and neither is a new field or an object saved for the first time.
  2. A new sibling code field that is blank leaves its rows codeless, with the same consequences as a switch into record mode. Fill it with the backfill above (os migrate record-currency-codes, or its REST door). A path stores no code on the child, so there is nothing to backfill: each row follows its parent record.
  3. Stored home amounts are not re-rated. If the amount declares homeAmount, its stored home amounts and rates were converted from the old code. Re-derive them from the new one with os migrate recompute-home-amounts, which is a shell command with no REST door. If the save also removes homeAmount, nothing re-rates them.

Aggregating a record-mode amount

Amounts in different currencies do not add. A sum, avg, min or max over a record-mode amount is refused with INVALID_FIELD / 400 unless the same query groups by the amount's code field, and the query is not run. Grouped by the code, every group holds one currency and each figure is right.

// Refused: USD 100 and EUR 100 would answer 200 under one label.
{ aggregations: [{ function: 'sum', field: 'amount', alias: 'total' }] }

// Served: one total per currency.
{ groupBy: ['currency_code'], aggregations: [{ function: 'sum', field: 'amount', alias: 'total' }] }

The rule holds at two doors:

  • The ObjectQL aggregate, so it covers every caller that reaches the engine: the REST query API, flows, hooks and the analytics strategy.
  • The analytics cube door, ahead of strategy selection: dataset queries (the main grid, every totals grouping including the grand total, and the compareTo pass), cube queries over a declared or inferred cube, and the dataset draft preview.

A count reads no amount and is always served, grouped or not, and so is count_distinct. A where that happens to select one currency does not count as grouping: the rule is the grouping alone.

In an analytics answer, a measure column over a record-mode amount, grouped by the code, carries currencyField instead of currency. It names the dimension column of the same answer that groups by the code field, and each row's currency is that row's value of that column. A count column never carries currencyField. See the analytics result columns for the full fields[] surface.

Roll-ups and datasets

  • A summary roll-up whose sum, avg, min or max reads a record-mode amount of the child object is refused when the object registers, with INVALID_METADATA / 422. A roll-up stores one number with no currency, so child rows in different currencies would be added together. Use function: 'count'. The pair is judged at whichever registration completes it, the parent's or the child's.
  • A summary declaring currencyMode: 'record' is admitted only for a roll-up through the master_detail its child amounts follow (PARENT_FIELD.CODE_FIELD), and names the parent's own code field. One whose child amount follows no record (a fixed amount, a dynamic one, a plain number) totals in no currency the parent holds: defineStack refuses it, and on a running server a save or publish through the metadata API refuses it with INVALID_METADATA / 422 and the same message, whichever object is saved second.
  • A dataset measure that declares currency over a record-mode amount is refused at compile with DATASET_INVALID / 400, and so is a currency on a derived measure that sums record-mode amounts. One code cannot label amounts in several currencies: delete the measure's currency and select the dimension over the code field, so each row carries its own.
  • A derived measure that combines a record-mode amount with an amount in another currency (another code field, a fixed code, an explicit measure code or the tenant currency) is refused at compile with DATASET_INVALID / 400, whatever the operation. A derived measure over a count, such as an amount per invoice, stays legal.
  • A dataset measure whose currency differs from its field's fixed code is refused at compile with DATASET_INVALID / 400: currency: 'USD' over a field fixed to EUR would label euros as dollars. Delete the measure's currency, and the column takes the field's code. A currency that restates the field's code is accepted.
  • A derived measure whose monetary operands resolve to two different fixed codes is refused at compile with DATASET_INVALID / 400, whatever the operation. Derive it from measures in one currency, or drop the operand in the other. A derived sum or difference over one fixed code carries that code, on its result column too, so a measure built on it is judged the same way.
  • A derived sum or difference whose currency differs from its operands' one fixed code is refused at compile with DATASET_INVALID / 400: currency: 'USD' over two measures fixed to EUR would print euros as dollars. Delete the measure's currency, and the column takes the operands' code, or restate that code.
  • Not judged: a fixed code against the tenant currency, which compile does not know, and a measure currency over a dynamic field, which wins as the top of the currency chain.

In the Console

Each record-mode amount shows the symbol and minor-unit decimals of its own record's code. A record whose code is blank shows a plain number. Grouped analytics answers do the same per row: the dashboard table, the report table and its export, and the Studio dataset preview each take a row's currency from its code column. A place that spans many records and is not grouped by the code has no one currency to show: the grid footer draws no sum / avg / min / max for that column, a group header draws them only when the grouping includes the code field, a report's grand total on such a column shows no symbol, and the counts always stand.

The home currency

The organization's home currency is the existing localization.currency setting. Metadata never names it: no field, object or dataset declares the home currency, and a dynamic amount displays in it because that is what dynamic means.

To total record-mode amounts across currencies, store each one converted into the home currency when it is written, as the next section shows, and aggregate the stored home amount.

Converting into the home currency

Declaring the home amount

A record-mode amount declares currencyConfig.homeAmount to have the engine store its value converted into the home currency, together with the rate it used. The declaration names three fields of the same object, all required:

PointerNamesDeclared as
fieldwhere the home amount is storeda currency field in dynamic mode (it displays in the home currency), readonly: true
rateDatethe record's document date, which picks the ratea date or datetime field. There is no default: the engine never uses created_at in its place.
rateFieldwhere the rate used is storeda number field, readonly: true
export const Invoice = ObjectSchema.create({
  name: 'invoice',
  label: 'Invoice',
  fields: {
    name: Field.text({ label: 'Number', required: true }),
    currency_code: Field.text({ label: 'Currency', valueDomain: 'iso_4217_currency' }),
    invoice_date: Field.date({ label: 'Invoice Date' }),
    amount: Field.currency({
      label: 'Amount',
      currencyConfig: {
        currencyMode: 'record',
        currencyField: 'currency_code',
        homeAmount: { field: 'amount_home', rateDate: 'invoice_date', rateField: 'amount_rate' },
      },
    }),
    amount_home: Field.currency({ label: 'Amount (home currency)', readonly: true }),
    amount_rate: Field.number({ label: 'Exchange rate', readonly: true }),
  },
});

The names amount_home and amount_rate are a convention, not a contract: the platform never injects these columns and never looks them up by name.

The exchange rates

Rates live in the organization's Exchange Rates (Setup, the sys_exchange_rate object): one row per currency and effective date, entered by an organization administrator, imported, or written by an app flow that fetches a provider feed. A rate states how many units of the foreign currency one unit of the home currency buys: with home currency USD, an EUR row of 0.92 means 1 USD = 0.92 EUR. A rate keeps up to twelve decimals.

A year of rates loads from one CSV with the columns currency, rate and effective_date, through the list page's Import or the generic import door (POST /api/v1/data/sys_exchange_rate/import/jobs). A line repeating a currency and effective date already on file is refused for that row alone (UNIQUE_VIOLATION) and the rest of the file still lands; add a source column reading import to mark the rows imported, since an omitted one takes the default, manual.

What a write stores

When a record is inserted, and whenever an update changes its amount, its code or its document date, the engine computes the home amount:

  • The rate is the row for the record's currency with the latest effective date on or before the document date. A row dated after the document never applies, and neither does "the most recent rate" when it is dated later. A datetime document date is dated in the organization's timezone (the localization.timezone setting, UTC when unset): an invoice written at 01:00 on April 1 in Shanghai takes the April 1 rate. A date document date is its own day.
  • The home amount is the amount divided by the rate, computed in exact decimal arithmetic and rounded once, half away from zero, to the home currency's decimal places as CLDR gives them (its fraction digits, not ISO 4217's minor units): 0 for JPY, 2 for USD and CNY, 3 for KWD. For sixteen currencies the two differ, and CLDR's count applies: IQD has 0 (ISO 4217: 3), and AFN, ALL, COP, HUF, IDR, IRR, KPW, LAK, LBP, MGA, MMK, PKR, SOS, SYP and YER have 0 (ISO 4217: 2), so a home amount in any of them is rounded to whole units. USD 10,000 at a rate of 0.1389 into CNY stores ¥71,994.24.
  • The rate field stores the rate row's own value, unrounded, so the stored home amount always reproduces from the stored amount and rate.
  • An amount in the home currency itself stores rate 1 and needs no rate row.
  • A blank amount stores a blank home amount and a blank rate.

The home and rate fields are the engine's alone. A value a caller sends for either is dropped like any readonly value (or refused under strictReadonlyWrites); a defaultValue on either never stands; and a value a system write or a historical import supplies is computed over. A batch insert and an import convert every row through the same path as a single write.

A rate row corrected later does not rewrite the amounts already converted with it: an update that does not touch the amount, its code or its document date leaves the stored home amount and rate as they are. To bring stored rows up to the rates in force now, run the recompute.

An update by filter (multi: true) writes one patch to every matched row, so it is refused, with VALIDATION_FAILED, when the patch would convert the rows to different home amounts. Update those rows by id instead, and each is converted from its own row.

What a write refuses

Each refusal is answered before anything is written, and the row is not stored:

RefusalWhenFix
ERR_EXCHANGE_RATE_MISSING / 400No rate row for the record's currency has an effective date on or before its document date. The message names the currency and the date.Add a rate for that currency effective on or before that date, then write again. The engine never stores a rate of 1, a later rate or an empty home amount in its place.
ERR_HOME_CURRENCY_UNSET / 400The organization has no home currency: localization.currency is not set.Set Localization → Default currency, then write again. The platform never assumes a home currency.
VALIDATION_FAILED / 400, required on the date fieldA foreign-currency amount has a blank document date.Write the document date in the same write.

The validate() preview, and an import's dry run, answer the same refusals for the same rows.

Recomputing stored home amounts

os migrate recompute-home-amounts brings the stored home amounts of an object up to the rates in force now: after a rate row is corrected or added, or after a home amount is declared on an object that already holds rows.

os migrate recompute-home-amounts --object invoice                          # Report: what would change, what cannot be converted
os migrate recompute-home-amounts --object invoice --since 2026-01-01       # Only documents dated on or after January 1
os migrate recompute-home-amounts --object invoice --apply                  # Write the changes (prompts)

Each row is converted exactly as a write converts it, in its own organization's home currency at that organization's rates, and an applied row holds what a fresh write of it would store, so what reads the home field (formulas, roll-ups, the audit trail) follows as it does for a fresh write. The row's updated_at is kept: an integration that syncs by updated_at does not see the recomputed value until it resyncs the object. --since compares the document date (the field homeAmount.rateDate names), read as the day the write reads it. The report counts each organization apart and lists every row that changes, with its stored and new values.

A row that cannot be converted is listed and left as stored, never filled with a rate of 1, a later rate or a zero. The report names each one and why: no rate in force on its document date (add the rate), an amount with no currency code (run os migrate record-currency-codes first: no rate can help a row that names no currency; give it --org for each organization's code), no document date, or no home currency. Until a re-run converts them, a total over the home field leaves those rows out, so the command keeps exiting 1 while any is listed, and the applied run's audit entry records them. The full reference is os migrate recompute-home-amounts.

Totals in the home currency

The home field is an ordinary stored currency field, so every aggregate reads it as it reads any amount: a sum over amount_home is the consolidated total, with no grouping, and a summary roll-up, a dataset measure or a grid footer over it needs nothing special.

See also

On this page