DEV Community

allratestoday
allratestoday

Posted on

Display at the Market Rate, Book at the Official Rate: A Two-Rate Pattern for E-Commerce

A store that sells in several currencies runs into this sooner or later: the price a customer saw at checkout, the amount that landed in your account, and the figure your accountant needs are three different numbers.

You can't remove that difference, but you can record it properly.

The pattern

Store two rates on every order, from two different layers:

Field Source Why
display_rate Live mid-market (/api/v1/rates) What the customer was shown. Refreshed every 60 seconds.
book_rate Official rate (/api/v1/central-bank/{source}/latest) What your ledger and tax return use. Fixed per day.

Plus the metadata that makes each one auditable: display_rate_time, book_rate_source, book_rate_date.

const KEY = process.env.ALLRATES_KEY;
const H = { Authorization: `Bearer ${KEY}` };

async function ratesForOrder(from, to, bookSource) {
  const [live, official] = await Promise.all([
    fetch(`https://allratestoday.com/api/v1/rates?source=${from}&target=${to}`, { headers: H }).then((r) => r.json()),
    fetch(`https://allratestoday.com/api/v1/central-bank/${bookSource}/latest?source=${from}&target=${to}`, { headers: H }).then((r) => r.json()),
  ]);
  return {
    display_rate: live[0].rate,          // the response is an array, even for one pair
    display_rate_time: live[0].time,
    book_rate: official.rate,
    book_rate_source: bookSource,
    book_rate_date: official.rate_date,
  };
}

// A UK store selling in USD, booking at HMRC's monthly rate
const rates = await ratesForOrder('USD', 'GBP', 'hmrc');
Enter fullscreen mode Exit fullscreen mode

Pricing many currencies at once

A product page priced in a dozen currencies only needs one request: target=EUR,GBP,JPY,CAD,... returns them all in one array, and it counts as one call. Cache it for a minute and you have live prices with very little traffic.

The third rate: settlement

When your payment provider or bank converts the money, it applies its own rate. If you settle through a bank whose board AllRatesToday covers, /api/v1/bank-rates/{country}/{bank}?ccy=USD gives you that bank's buy and sell, so you can reconcile what arrived against what was expected.

Display, book and settle make three rates. AllRatesToday serves all three from one key, and we haven't found another API that does, so the pattern above needs a single integration.

Docs: allratestoday.com/docs ยท Free key: allratestoday.com/register

Top comments (0)