Using Currency Codes in REST APIs

Currency Codes in API Design

When designing REST APIs that handle monetary values, consistent and unambiguous representation of currencies is critical. Using ISO 4217 codes is the industry standard, but the specifics of how amounts and currencies are structured in API payloads vary.

Common JSON Patterns

Pattern 1: Separate amount and currency fields

{
  "amount": 29.99,
  "currency": "USD"
}

Simple but prone to floating-point precision issues.

Pattern 2: Amount in minor units (recommended)

{
  "amount": 2999,
  "currency": "USD"
}

Stripe, PayPal, and most payment processors use this pattern. The amount is in the smallest currency unit (cents for USD, yen for JPY). This avoids floating-point issues entirely.

Pattern 3: String amount

{
  "amount": "29.99",
  "currency": "USD"
}

Used when precise decimal representation is needed without worrying about JSON number parsing.

Best Practices

1. Always include the currency code — Never assume USD or any default
2. Use ISO 4217 alphabetic codes — "USD" not "usd", "$", or "dollar"
3. Document your unit convention — Clearly state if amounts are in major units (29.99) or minor units (2999)
4. Be consistent — Don't mix patterns across endpoints
5. Include the numeric code when supporting systems that can't handle alphabetic codes
6. Validate currency codes against the ISO 4217 list on the server side

Handling Multiple Currencies

{
  "prices": [
    { "amount": 2999, "currency": "USD" },
    { "amount": 2499, "currency": "EUR" },
    { "amount": 3499, "currency": "GBP" }
  ]
}

Zero-Decimal Currencies

For JPY, KRW, and other zero-decimal currencies, the minor unit IS the major unit:

{ "amount": 1000, "currency": "JPY" }
// This means 1000 yen, NOT 10.00 yen

Always check the currency's minor unit count before converting between major and minor units.