Currency Formatting

Get the formatter

const formatter = await komerza.createFormatter();

formatter.format(variant.cost); // "$29.99"

createFormatter() resolves to a standard Intl.NumberFormat set up for the store. format(), formatToParts() and formatRange() all work as usual.

Adaptive currency

If the merchant has turned on adaptive currency, shoppers see prices in their own currency. The formatter is how that reaches your storefront: it converts as it formats. The shopper’s currency comes from their browser’s language and region, so a US store’s 29.99 shows in dollars for most US shoppers and in pounds for one whose browser is set to British English. That’s why the rules are strict:

Pass amounts exactly as the API gives them. cost and every other price in store data is in the store’s currency, store.currencyCode. Don’t convert or round them first.
Format every price with it. A price printed any other way - "$" + cost, or cost.toFixed(2) - is in the wrong currency for those shoppers, while the checkout they reach is in the right one.
Never hardcode a currency symbol, not even as a placeholder while the formatter loads. On an adaptive-currency store, a $ placeholder is the wrong currency, and it’s the first thing shoppers see.

The rate the buyer pays at is fixed when the order is created, and the hosted checkout shows them the same currency.

Examples

const formatter = await komerza.createFormatter();

formatter.format(9.99); // "$9.99"
formatter.format(1499.5); // "$1,499.50"
formatter.format(29.999); // "$30.00" - rounded to the currency's decimals

Numbers use US-English formatting whatever the currency:

Currency	`format(29.99)`
USD	$29.99
EUR	€29.99
GBP	£29.99
CAD	CA$29.99
AUD	A$29.99
JPY	¥30

A price range

function priceRange(product, formatter) {
  const prices = product.variants.map((variant) => variant.cost);
  const min = Math.min(...prices);
  const max = Math.max(...prices);

  return min === max ? formatter.format(min) : formatter.formatRange(min, max);
}
// "$5.00 – $10.00"

A cart total

Add up amounts in the store’s currency, then format the total once:

async function cartTotal() {
  const [response, formatter] = await Promise.all([
    komerza.getStore(),
    komerza.createFormatter(),
  ]);
  if (!response.success) return null;

  const products = response.data.products;
  let total = 0;

  for (const item of komerza.getBasket()) {
    const product = products.find((p) => p.id === item.productId);
    const variant = product?.variants.find((v) => v.id === item.variantId);
    if (variant) total += variant.cost * item.quantity;
  }

  return formatter.format(total);
}

This is an estimate for display. Volume pricing, coupons and fees are worked out at checkout - see volume pricing.

Styling part of a price

formatToParts() splits a price so you can style the pieces - here, a smaller currency symbol:

function priceElement(amount, formatter) {
  const span = document.createElement("span");

  for (const part of formatter.formatToParts(amount)) {
    const piece = document.createElement("span");
    piece.textContent = part.value;
    if (part.type === "currency") piece.className = "price-symbol";
    span.append(piece);
  }

  return span;
}

The parts are already converted, so the symbol is whatever the shopper’s currency uses.

Loading and caching

The SDK caches the formatter, so call createFormatter() wherever you need it - every call after the first resolves straight away. init() starts preparing it in the background too. If you keep your own copy, keep only a formatter the call actually returned:

let formatter = null;

async function getFormatter() {
  if (!formatter) formatter = await komerza.createFormatter();
  return formatter;
}

Don’t catch a failure and store a fallback such as new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }) in its place. A cached fallback is permanent: one early failure would show every price on the page in the wrong currency for the rest of the visit. Leave the cache empty and try again on the next render, and show a skeleton - not a $0.00 - until it resolves.

Products

Variants, stock and volume pricing

Basket

The cart, and rendering it with prices

Getting Started

Client Library

Get the formatter

Adaptive currency

Examples

A price range

A cart total

Styling part of a price

Loading and caching

Next

Products

Basket

​Get the formatter

​Adaptive currency

​Examples

​A price range

​A cart total

​Styling part of a price

​Loading and caching

​Next

Products

Basket

Get the formatter

Adaptive currency

Examples

A price range

A cart total

Styling part of a price

Loading and caching

Next