Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 40 ยท Pricing, Promotions, Tax

Currencies and Localization

Sell worldwide: multi-currency pricing, exchange rates and when to lock them, rounding rules, Intl.NumberFormat, locales, address and phone formats, time zones.

The first customer from another country exposes every assumption in your shop. A price shown as "1.234,50" is a bargain or a mistake depending on the reader. A Japanese yen has no cents. A sale that ends "at midnight" ends at three different times. A postal code field that insists on five digits rejects half of Europe.

Localization is the work of making the shop correct and comfortable for people in different places. This lesson covers its money side (currencies, exchange rates, rounding, formatting) and the data side (locales, addresses, phone numbers, time zones). Amounts stay in integer minor units, as described in Representing Money Correctly, and tax display rules from Sales Tax, VAT and GST apply per market.

Two ways to do multi-currency pricing

1. Convert on the fly. Keep prices in one base currency and multiply by an exchange rate for display and checkout. This is simple and needs no extra price data, but prices wobble with the market, they look odd (54.20 instead of 54.99), and rounding is on you.

2. Explicit prices per currency. Store a price for each currency in a price list (eur, usd, gbp), as described in Pricing Models. Merchandisers can set 59.00 USD for a 49.99 EUR item, apply psychological price points, and reflect local competition. It means more data to maintain.

Many shops combine them: explicit prices for the main markets, automatic conversion with rounding rules for the long tail. Whichever you choose, the currency is part of every money value, on carts, orders, refunds, invoices and reports. A bare number is not an amount.

Presentment currency versus settlement currency

The presentment currency is what the shopper sees and pays in. The settlement currency is what lands in your bank account. If they differ, someone converts, and takes a margin: your payment provider, the customer's bank, or you. Decide who carries the exchange risk. Many providers let a customer pay in a local currency while you receive your own, with the rate fixed at the time of payment.

Exchange rates: when to lock them

Rates move constantly, so the question is when a rate becomes final. Use one rule consistently:

  • Fetch rates on a schedule (hourly or daily) from a rate provider and cache them. Do not call an external API on every page view.
  • Add a margin (for example 1 to 3 percent) to cover movement and payment fees, if your business model allows it.
  • Lock the rate at checkout. The displayed total must equal the charged total, so the rate used for the cart is saved on the cart and stays fixed for a short window.
  • Store the rate on the order, together with the converted amount. A refund returns the amount the customer paid, not a new conversion with today's rate.
flowchart LR
    R["Rate provider<br/>fetched hourly, cached"] --> C["Cart<br/>rate locked for 15 min"]
    C --> O["Order<br/>stores rate + charged amount"]
    O --> F["Refund<br/>reuses the stored amount"]
    R -.-> D["Display on product pages<br/>approximate, cached"]

The rate is fixed at checkout and travels with the order; product pages can use a cached, approximate rate.

Minor units and rounding rules

A currency has an exponent: the number of digits after the decimal point in its smallest unit. Dollars and euros have two. The Japanese yen has zero. The Kuwaiti dinar has three. Code that multiplies by 100 everywhere will charge a yen customer a hundred times the intended price. Read the exponent from a currency table, never from a constant.

Converted prices need a rounding rule before they are shown:

  • Plain rounding to the minor unit is accurate but gives odd-looking prices.
  • Price endings (psychological pricing): round up to .99, .95 or .00. For yen, a multiple of 10 or 100; for three-decimal currencies, a multiple of 0.050. Round up, so the margin is not lost.
  • Cash rounding: some places have no smallest coin (for example 5 cents), so cash totals get rounded. Online card payments are normally exact.

The following program does all of this. It converts a 49.99 EUR price into three currencies with different exponents, applies an ending rule, formats the result with Intl.NumberFormat, and then shows why the rate must be stored with the order. (Floating-point is used here only to keep the demo short; production code multiplies decimals or integers and rounds once.)

JS Convert, round, lock the rate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The dollar price converts to $54.20 and is lifted to $54.99. The yen price has no fractional part (8,177 yen becomes 8,180), and the dinar price is rounded up to a multiple of 0.050. The last three lines make the rule concrete: if you recomputed a refund with a later rate, the customer who paid $54.20 would get $55.99 back, which is wrong in the customer's favour or against it depending on which way the rate moved.

Formatting with Intl

Never build money strings with string concatenation ("$" + amount). Position of the symbol, separators, grouping and even the digits differ by locale. Browsers and Node include the Intl API, which implements these rules from locale data. Its output can vary a little between engines and versions, so never parse a formatted string back into a number.

JS One amount, many locales

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The German and French outputs put the symbol after the number and use different separators, the Indian format groups digits as 12,34,567, and the dinar shows three decimals while the yen shows none. (The plain helper only turns the no-break spaces that Intl inserts into normal spaces so the output prints cleanly.) Intl also formats dates, relative times, lists and plurals. Use it on the client or in server-side JavaScript, and use your framework's equivalent (for example PHP's NumberFormatter or ICU-based libraries) on other backends.

Locales: language, region and format

A locale such as fr-CA combines a language (French) and a region (Canada). They control text, number and date formats, sort order and units. Keep these separate in your model:

  • The shopper's language (text translation, covered in Product Catalogs and Data Modeling).
  • The shopper's market or country (price list, currency, tax rules, shipping options).
  • The shopper's currency, which may differ from both (an English speaker in Switzerland paying in francs).

Choose defaults from the URL (/de/, a subdomain, or a country domain), not from IP address alone, and always let the shopper switch. For SEO, each language version needs its own URL (see SEO for Online Shops).

Addresses and phone numbers

Address forms are a classic localization failure. Rules differ by country:

Aspect Variation
Order of fields Number before or after the street name; postal code before or after the city
State or province Required in the US and Canada, meaningless in many countries
Postal code Absent in some countries, alphanumeric in others (UK, Canada), different lengths
Names One name field, two, or family name first
Phone Country code plus national number, with different lengths

Practical guidance:

  • Ask for country first, then adapt the other fields (labels, which are required, postal code pattern).
  • Validate loosely. A strict pattern that rejects real addresses costs more sales than a typo costs deliveries. Use a postal address service for suggestions if the budget allows.
  • Store addresses as structured fields (line 1, line 2, city, region, postal code, country as an ISO code), not one text blob.
  • Store phone numbers in the E.164 form (+4930123456) and format them for display with a library.
  • Allow Unicode in names and addresses. Do not assume ASCII.

Time zones

Dates and times cause quiet bugs in multi-region shops: sale windows, delivery cut-offs, email send times, "orders placed today" reports. The rules that prevent most of them:

  1. Store instants in UTC (a timestamp in the database is a moment in time, not a wall-clock reading).
  2. Store each store's, warehouse's and, where it matters, customer's IANA time zone name (such as Europe/Berlin), not a fixed offset, because daylight saving time changes offsets.
  3. Convert to a local time zone only at the edges: display and parsing of user input.
  4. Define scheduled events (sales, cut-off times) in a named time zone and convert to a UTC instant, then compare instants.
JS One instant, four wall clocks

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The same instant reads 23:59 in Berlin, 17:59 in New York and already 1 December in Tokyo and Auckland. Tell shoppers which zone a deadline uses ("ends 30 Nov, 23:59 CET"), or show it converted for them. Comparing instants (now <= saleEnd) is always safe; comparing formatted local strings is not.

Test with at least one zero-decimal currency (JPY), one three-decimal currency (KWD), one right-to-left language (Arabic or Hebrew) and one country without postal codes. Those four cases uncover most localization assumptions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should the exchange rate be stored on the order?

    Rates change constantly. The order must record the rate and charged amount so a refund returns exactly what was paid.
  2. 2. A shop multiplies every price by 100 to get minor units. What goes wrong for Japanese yen?

    The yen exponent is 0, so 1,000 yen is 1000 minor units. Read the exponent from a currency table instead of hard-coding two decimals.
  3. 3. What is the best way to compare whether a time-limited sale is still active for shoppers in different time zones?

    Instants are unambiguous. Local wall-clock strings depend on time zone and daylight saving.
  4. 4. How should phone numbers be stored for an international shop?

    A normalized E.164 value is unambiguous and works with SMS and carrier APIs. Display formatting is a separate concern.

Summary

  • Choose between converting from a base currency and storing explicit prices per currency, and keep the currency with every amount.
  • Fetch and cache rates, lock the rate at checkout, and store it with the order so refunds reverse exactly.
  • Use each currency's exponent, apply an explicit rounding or price-ending rule, and always round up when protecting margin.
  • Format with Intl.NumberFormat (or the platform's ICU equivalent) and never parse formatted strings.
  • Separate language, market and currency; ask for the country first in address forms; store addresses as fields and phones as E.164.
  • Store instants in UTC, keep IANA zone names for places, and convert only for display.

Next: Designing the Cart.