Represent money as two fields: an integer amount in the currency's smallest unit (cents, pence, fils) plus an ISO 4217 currency code — never a float. Floats introduce binary rounding error that compounds across tax, discounts, and settlement math, producing off-by-one-cent bugs that surface in reconciliation, not code review.
Quick Answer: Store money as
{ amount: 1999, currency: "USD" }— an integer in minor units plus an ISO 4217 code — never{ price: 19.99 }. Round once, at the point of calculation, with a fixed rule, and format for locale only at render time.
If you're designing or reviewing a fintech, commerce, or billing API, this single decision — how a price is typed in the schema — will outlive every other design choice you make this quarter. Get it wrong and it's a breaking change to fix later; get it right once and every endpoint that touches money inherits the same guarantee.
Why a Float Is the Wrong Type for Money
A float is wrong for money because IEEE 754 double-precision binary floating point cannot exactly represent most decimal fractions — including $0.10 and $0.20 — so arithmetic on them accumulates tiny errors that surface as real accounting discrepancies. The fix isn't a rounding tweak; it's choosing a different representation entirely.
Binary floating point stores numbers as sums of powers of two. Decimal fractions like 0.1 or 0.2 don't terminate in binary any more than 1/3 terminates in decimal, so they're stored as the closest representable approximation. Anyone who's typed 0.1 + 0.2 into a JavaScript console and gotten 0.30000000000000004 has seen this directly — it's documented in detail in David Goldberg's widely cited 1991 paper "What Every Computer Scientist Should Know About Floating-Point Arithmetic," still the canonical reference on the topic.
For a physics simulation, that error is noise. For money, it's a discrepancy someone in finance has to explain. The failure modes compound in predictable places:
- Tax and fee calculations — multiplying a float subtotal by a float rate stacks rounding error before you've even rounded once.
- Multi-line invoices — summing dozens of float line items drifts further from the "true" total than any single line item would.
- Currency conversion — chained float multiplications (amount × rate × rate) amplify error with every hop.
- Cross-language serialization — a float that round-trips cleanly through one language's JSON parser may not through another's.
None of this means JSON itself is unsafe for money — a JSON number holding a plain integer like 1999 is exact up to 2^53 in any standards-compliant parser. The danger is specifically the decimal fraction — 19.99 — not the JSON number type in general. That distinction is the entire fix.
The Correct Contract: Minor Units Plus a Currency Code
The correct contract represents an amount as an integer count of the currency's smallest unit — cents for USD, pence for GBP — paired with an explicit ISO 4217 currency code in the same object: { amount: 1999, currency: "USD" } for $19.99. This makes the value exact, currency-aware, and safe to pass through any language's native integer type.
Compare the two shapes directly:
// Bad — float, no currency, ambiguous precision
{ "price": 19.99 }
// Good — integer minor units + explicit currency
{ "amount": 1999, "currency": "USD" }
The bad version fails in three independent ways: the float can't be trusted in arithmetic, there's no currency attached so a client has to assume one, and there's no signal for how many decimal places 19.99 even means in a currency where that might not be two. The good version fixes all three with two scalar fields.
| Approach | Example | Exact in arithmetic? | Currency explicit? | Verdict |
|---|---|---|---|---|
| Float decimal | 19.99 | No — binary rounding error | No | Avoid |
| String decimal | "19.99" | Yes, if parsed as fixed-point | No (usually) | Workable but awkward across languages |
| Integer minor units | 1999 | Yes — native integer math | Only if paired with a currency field | Recommended |
This isn't a novel invention — it's the same shape Martin Fowler formalized as the Money value object in Patterns of Enterprise Application Architecture (2002): amount plus currency, treated as one inseparable unit, never passed around separately. Stripe's public API documentation follows the identical convention, expressing every amount as an integer in the currency's smallest unit.
Google's API design guidance goes further, shipping a reusable google.type.Money protobuf message with exactly these two fields. This pattern is standard practice among the API designers building today's high-scale money endpoints, not an idiosyncratic preference.
The currency code matters as much as the integer. An amount without a currency forces every consumer to guess or hardcode a default, which quietly breaks the moment your product goes multi-currency. Treat Money as a single reusable shape referenced everywhere a price appears, the same discipline covered in guidance on modeling API resources around real-world nouns rather than ad hoc, endpoint-specific fields.
Validating Money at the API Boundary
A Money shape in a schema is only as safe as the validation behind it. Reject anything that doesn't match the contract at the boundary, rather than trusting downstream code to catch a malformed value after it's already been logged, queued, or persisted.
At minimum, validate:
currencyis a recognized ISO 4217 code — reject unknown or malformed codes ("US"instead of"USD") rather than defaulting silently to your home currency.amountis an integer, not a float or a numeric string with a decimal point — a request body containing"amount": 19.99should fail validation, not get silently truncated to19.- Negative amounts are an explicit, documented decision, not an accident — a refund or credit endpoint might legitimately accept a negative
amount, but a checkout endpoint almost certainly shouldn't, and the schema should say which. - An upper bound exists on
amountfor the endpoint — a missing bound turns a fat-fingered extra zero or an integer-overflow edge case into a five- or six-figure charge instead of a rejected request.
Rounding: Decide Once, Decide Deliberately
Rounding should happen exactly once, at the single point a fractional result is produced — a tax calculation, a discount split, a currency conversion — never on intermediate values that get added again afterward. Pick one rounding rule up front (typically round-half-up or round-half-to-even) and apply it consistently across every endpoint, not per feature team.
The classic failure is splitting an amount and letting the pieces silently lose or gain a cent. Split $10.00 three ways naively and you get $3.33 + $3.33 + $3.33 = $9.99 — a cent has vanished. The fix, sometimes called an "allocate" algorithm (again from Fowler's Money pattern), distributes the remainder deterministically:
- Divide the total in integer minor units by the number of shares, keeping the integer quotient and remainder.
- Assign the base quotient to every share.
- Distribute the leftover remainder, one minor unit at a time, to the first n shares (or by a documented rule such as largest-remainder-first).
- Verify the shares sum back to the original total before returning them — this is a cheap, deterministic assertion, not a "hope it works."
For rates and taxes, decide which side rounds: does the server compute tax at full precision internally and round only the final total, or round line-by-line? Whichever you pick, document it in the contract — this decision belongs in the same conversation as choosing between REST, RPC, and GraphQL, since a computed total field needs to behave identically regardless of which style you land on. A client should never be trusted to do this math itself; the server returns the already-rounded, already-correct amount.
Rule of thumb: if two independently written clients could compute two different totals from the same raw inputs, the rounding rule lives in the wrong place. Move it server-side and return the final integer.
Zero-Decimal, Three-Decimal, and Other Currency Exceptions
Not every currency has two decimal places, so amount: 1999 doesn't universally mean "$19.99 divided by 100." ISO 4217 publishes a minor unit exponent per currency — JPY and KRW use zero decimal places, while BHD, KWD, and OMR use three — and hardcoding "always divide by 100" silently produces amounts wrong by a factor of 100 or 1,000.
This is one of the most common real-world bugs in payment integrations, and it's well documented: Stripe, for instance, maintains a public list of "zero-decimal currencies" precisely because so many integrators assume cents-style division everywhere. For JPY, { amount: 1999, currency: "JPY" } means ¥1,999, not ¥19.99 — there is no minor unit to divide by.
| Currency | ISO 4217 code | Minor unit exponent | amount: 1999 means |
|---|---|---|---|
| US Dollar | USD | 2 | $19.99 |
| Euro | EUR | 2 | €19.99 |
| Japanese Yen | JPY | 0 | ¥1,999 |
| South Korean Won | KRW | 0 | ₩1,999 |
| Bahraini Dinar | BHD | 3 | BHD 1.999 |
| Kuwaiti Dinar | KWD | 3 | KWD 1.999 |
Do not hardcode the exponent anywhere in application logic. Look it up from a currency table keyed by the ISO 4217 code — the same table your API contract already references — and use it every time you convert between minor units and a display value. A currency's exponent can even change: ISO periodically issues amendments, most recently around redenominations of national currencies, so treat the table as data to maintain, not a constant to inline.
Formatting Is a Locale Concern, Not a Storage Concern
Locale formatting — symbol placement, separators, right-to-left layout — is a presentation transform applied at render time from the amount and currency pair, never baked into the stored value. The same { amount: 1999, currency: "USD" } should render as "$19.99" for en-US and "19,99 $US" for fr-CA without the contract changing.
Keep this boundary explicit:
- The API returns data, not display strings:
amount(integer),currency(ISO 4217 code). Nothing about symbol position or separator character belongs in the response body. - The client formats for locale, typically with a built-in primitive like
Intl.NumberFormat(locale, { style: 'currency', currency })rather than string-concatenating a symbol. - Never cache a formatted string as if it were data — a support ticket, an invoice PDF, and a mobile app showing the same order should all derive their display from the same two source fields, not three independently-formatted copies that can drift.
This boundary matters most exactly where a customer sees the number repeatedly across a single purchase — cart, checkout, confirmation email, refund notice — the kind of multi-touchpoint sequence you'd map out when documenting a full customer journey. If any one of those touchpoints formats from a cached string instead of the live amount/currency pair, a currency change or a correction after checkout won't propagate, and the customer sees two different totals for the same order.
Getting this right is also, plainly, part of the job a fintech or commerce API is hired to do: let an integrator in Tokyo and an integrator in Toronto both build correct checkout flows against the identical contract, formatting locally without ever touching the underlying integer. That's a jobs-to-be-done lens applied to API design — the "job" isn't just "return a price," it's "return a price I can trust and localize without re-deriving your business logic."
Locking the Contract Before Anyone Writes Code
The amount-plus-currency convention only holds if it's specified in the API contract before implementation starts — in the schema, not as tribal knowledge in a Slack thread — so every endpoint touching money uses the identical shape. A Money object defined once and referenced everywhere is far cheaper to enforce than a style guide nobody rereads.
In practice that means the Money shape belongs in your shared schema components (an OpenAPI components/schemas/Money, a shared TypeScript type, a protobuf message) referenced by every request and response body that carries a price — line items, invoices, refunds, payouts — the same rigor described in guidance on specifying an API contract as a real PM deliverable rather than an afterthought. It's also a direct extension of resource modeling done well, one thread among many in a complete guide to API product design.
This is precisely the kind of decision that's inexpensive to fix in a spec and expensive to fix once client SDKs, database columns, and reconciliation reports all assume floats. Prodinja's API Designing tool lets you define money fields — amount, currency, the exact JSON shape — directly in the request and response contract before a single endpoint is implemented, so the integer-plus-currency-code convention is locked in the design artifact itself rather than discovered as a bug three sprints later.
Key Takeaways
- Never store or transmit a price as a float. IEEE 754 binary floating point can't exactly represent most decimal fractions, and the resulting rounding error compounds across tax, discounts, and multi-line totals.
- Use integer minor units plus an explicit ISO 4217 currency code —
{ amount: 1999, currency: "USD" }— as the oneMoneyshape referenced by every endpoint that carries a price. - Round exactly once, at the point a fractional result is produced, using a documented rule (round-half-up or round-half-to-even) applied server-side — never trust a client to reproduce the same rounding.
- Don't hardcode a "divide by 100" assumption. Zero-decimal currencies like JPY and KRW and three-decimal currencies like BHD and KWD break that assumption; look up the minor unit exponent from an ISO 4217-keyed table instead.
- Separate the amount from its formatted display. Locale formatting is a render-time transform on
amount+currency, never a cached string stored alongside — or instead of — the source data. - Specify the
Moneycontract before coding begins. A shared schema component enforced across every endpoint is cheaper than a convention everyone is expected to remember.
Frequently Asked Questions
How should I represent money in JSON?
Represent an amount as an integer in the currency's smallest unit and pair it with an explicit ISO 4217 currency code in the same object — { "amount": 1999, "currency": "USD" } for $19.99. Avoid a bare float or a price field with no attached currency; both leave the value ambiguous and unsafe to compute with.
Why shouldn't I use a float or decimal type for currency amounts?
Because IEEE 754 double-precision floats can't exactly represent most decimal fractions, so arithmetic on them — summing line items, applying a tax rate, splitting a total — accumulates rounding error that shows up as real discrepancies in reconciliation. Integer minor-unit math avoids the problem entirely by never representing a fraction in the first place.
What is ISO 4217 and why does an API need it?
ISO 4217 is the international standard that assigns a three-letter code (USD, EUR, JPY) and a minor-unit exponent to every currency. An API needs it because an amount without an explicit currency code is unusable — a consumer can't tell $19.99 from ¥19.99 without it, and can't tell how many decimal places the integer represents.
How do zero-decimal currencies like JPY affect the amount field?
For a zero-decimal currency such as JPY or KRW, the integer amount field represents the whole currency unit directly — amount: 1999 for JPY means ¥1,999, not ¥19.99 — because there's no smaller minor unit to divide by. Look up each currency's exponent from an ISO 4217 table rather than assuming every currency divides by 100.
Should I ever store a formatted price string like "$19.99" in the database?
No — store the integer amount and the currency code, and generate any formatted string at render time using a locale-aware formatter. A cached formatted string can drift from the source data across locales, currencies, or after a correction, producing inconsistent totals across a customer's cart, invoice, and confirmation email.