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
currencyMode | The amount's currency | Keys 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 |
fixed | One currency for the whole column. | defaultCurrency, required |
record | Each 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:
| Declaration | Refused at | Fix |
|---|---|---|
currencyMode: 'record' with no currencyField | currencyConfig.currencyField | Name the code field, or use fixed (one currency) or dynamic (the tenant default). |
currencyField under dynamic or fixed | currencyConfig.currencyField | Set currencyMode: 'record', or delete currencyField. |
defaultCurrency under record | currencyConfig.defaultCurrency | Delete defaultCurrency, or use fixed if the field has one currency. |
currencyField: '' | currencyConfig.currencyField | Name a field. |
currencyField names no other field of the object, or names the amount itself | fields.<amount>.currencyConfig.currencyField | Point at a declared code field. The message lists the object's candidates. |
currencyField names a field that is not text | same | Point at a text field. |
currencyField names a text field without valueDomain: 'iso_4217_currency' | same | Add 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.
- The save answers 409
destructive_change. Saving the switched object reports the findingcurrency_mode_to_recordon the amount field, and the message names the command to run. Re-submit the save withforce(?force=trueonPUT /api/v1/meta/:type/:name) to make the switch. - Dry run.
os migrate record-currency-codes --object opportunity --field amount --code USDcounts the rows holding an amount and no code, and writes nothing. --apply. The same command with--applywrites 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.
- The save answers 409
destructive_change. Saving the re-pointed object reports the findingcurrency_field_repointedon the amount field. The save reads no row, so it reports the finding whether or not the table holds any. Re-submit withforce(?force=trueonPUT /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. - 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. - 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 withos migrate recompute-home-amounts, which is a shell command with no REST door. If the save also removeshomeAmount, 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
totalsgrouping including the grand total, and thecompareTopass), 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
summaryroll-up whosesum,avg,minormaxreads a record-mode amount of the child object is refused when the object registers, withINVALID_METADATA/ 422. A roll-up stores one number with no currency, so child rows in different currencies would be added together. Usefunction: 'count'. The pair is judged at whichever registration completes it, the parent's or the child's. - A
summarydeclaringcurrencyMode: 'record'is admitted only for a roll-up through themaster_detailits child amounts follow (PARENT_FIELD.CODE_FIELD), and names the parent's own code field. One whose child amount follows no record (afixedamount, adynamicone, a plain number) totals in no currency the parent holds:defineStackrefuses it, and on a running server a save or publish through the metadata API refuses it withINVALID_METADATA/ 422 and the same message, whichever object is saved second. - A dataset measure that declares
currencyover a record-mode amount is refused at compile withDATASET_INVALID/ 400, and so is acurrencyon a derived measure that sums record-mode amounts. One code cannot label amounts in several currencies: delete the measure'scurrencyand 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
fixedcode, an explicit measure code or the tenant currency) is refused at compile withDATASET_INVALID/ 400, whatever the operation. A derived measure over acount, such as an amount per invoice, stays legal. - A dataset measure whose
currencydiffers from its field'sfixedcode is refused at compile withDATASET_INVALID/ 400:currency: 'USD'over a field fixed toEURwould label euros as dollars. Delete the measure'scurrency, and the column takes the field's code. Acurrencythat restates the field's code is accepted. - A derived measure whose monetary operands resolve to two different
fixedcodes is refused at compile withDATASET_INVALID/ 400, whatever the operation. Derive it from measures in one currency, or drop the operand in the other. A derivedsumordifferenceover onefixedcode carries that code, on its result column too, so a measure built on it is judged the same way. - A derived
sumordifferencewhosecurrencydiffers from its operands' onefixedcode is refused at compile withDATASET_INVALID/ 400:currency: 'USD'over two measures fixed toEURwould print euros as dollars. Delete the measure'scurrency, and the column takes the operands' code, or restate that code. - Not judged: a
fixedcode against the tenant currency, which compile does not know, and a measurecurrencyover adynamicfield, 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:
| Pointer | Names | Declared as |
|---|---|---|
field | where the home amount is stored | a currency field in dynamic mode (it displays in the home currency), readonly: true |
rateDate | the record's document date, which picks the rate | a date or datetime field. There is no default: the engine never uses created_at in its place. |
rateField | where the rate used is stored | a 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
datetimedocument date is dated in the organization's timezone (thelocalization.timezonesetting, UTC when unset): an invoice written at 01:00 on April 1 in Shanghai takes the April 1 rate. Adatedocument 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
1and 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:
| Refusal | When | Fix |
|---|---|---|
ERR_EXCHANGE_RATE_MISSING / 400 | No 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 / 400 | The 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 field | A 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
- Field Type Gallery:
currency— the field's properties and decimal places. - Validation rules:
currency— the value shape a write is judged against. - Analytics — datasets, measures and dimensions.