0033: Money in bigint minor units

Money is stored as bigint minor units with a currency, replacing the numeric document money of ADR 0018.

Status: Proposed
Date: 2026-10-25

Context

ADR 0018 stores document money as numeric. The better-supabase commerce blocks (catalog, quotes, invoices with ledger, orders, shipments) store amounts as integer minor units with a currency, and ADR 0032 moves commerce onto those blocks.

Decision

Every money column becomes bigint minor units plus a currency column, in commerce, expenses, people rates and compensation, billing and platform fees.
The cutover uses expand and contract: add the columns, backfill, switch reads and writes, then drop the numeric columns.
The migration is tested first on a copy of the develop database, with a per-document check that totals match to the cent, before it reaches develop.
Contracts, OpenAPI, the API client, PDFs, AI tools and seeds switch with it; formatting goes through one money helper in @workspace/foundation.

This supersedes the money part of ADR 0018 once accepted.

Consequences

A breaking API change: openapi:generate and the API client change, and integrations must read minor units.
Rounding moves to integer arithmetic; VAT and discounts round once per line.

Status: Proposed
Date: 2026-10-25

Context

Decision

Every money column becomes bigint minor units plus a currency column, in commerce, expenses, people rates and compensation, billing and platform fees.
The cutover uses expand and contract: add the columns, backfill, switch reads and writes, then drop the numeric columns.
The migration is tested first on a copy of the develop database, with a per-document check that totals match to the cent, before it reaches develop.
Contracts, OpenAPI, the API client, PDFs, AI tools and seeds switch with it; formatting goes through one money helper in @workspace/foundation.

This supersedes the money part of ADR 0018 once accepted.

Consequences

A breaking API change: openapi:generate and the API client change, and integrations must read minor units.
Rounding moves to integer arithmetic; VAT and discounts round once per line.

0033: Money in bigint minor units

Context

Decision

Consequences

On this page

0033: Money in bigint minor units

Context

Decision

Consequences

On this page

0033: Money in bigint minor units

ContextCopy Anchor Link

DecisionCopy Anchor Link

ConsequencesCopy Anchor Link

On this page

0033: Money in bigint minor units

ContextCopy Anchor Link

DecisionCopy Anchor Link

ConsequencesCopy Anchor Link

On this page

Context

Decision

Consequences

Context

Decision

Consequences