Skip to content

Currencies and money ​

Two rules shape everything else on this page, and both are decisions rather than implementation details.

Amounts are integers in minor units ​

There are no floating-point numbers anywhere in the money path. €18.50 is stored as 1850. Prices, totals, discounts, delivery and refunds are all integers, and Support\Money is the only place where conversion to and from a human-readable form happens.

This is why a discount of 33% on one cent is zero rather than 0.33, and why a total never drifts by a cent after three additions.

Prices are fixed per currency, never converted ​

A product does not have "a price" plus a rate. It has a price in each currency you sell in, typed in by hand.

Why not a rate

Because "€18" converted from roubles is "€18.18", and nobody prices a product that way. A rate turns every price in your catalogue into an awkward number that changes behind your back, and a shop whose prices move daily looks broken rather than responsive.

The rate column does exist on a currency, and it is used for converting an amount where one is genuinely needed — reporting, totals across currencies. Product prices never go through it.

The consequence to plan for: a product with no price in the current currency is not sold in it. Its card prints no price, it is excluded from the offers in the structured data, and the checkout will not take it. Empty is not zero, and that distinction is load-bearing.

The currency reference ​

pb_shop_currencies, in the Currencies grid:

FieldWhat it holds
codethe ISO code — EUR, UAH, MDL
namethe display name
symbolthe symbol — €, ₴. Empty falls back to the code
exponentdecimal places in the minor unit; 2 for most, 0 for yen
ratehow much of the base currency one unit is worth
is_defaultthe storefront default. Exactly one
published_atan unpublished currency is not offered in the switcher

Both the symbol and the exponent are read from this table, so a currency the shop needs that nobody anticipated works by adding a row. Five common ones have built-in values as a fallback for when the table has nothing to say — EUR, USD, RUB, MDL, UAH — but the table wins whenever it has an entry.

A soft-deleted or unpublished currency keeps its symbol and exponent for rendering, so an old order in a currency you stopped selling in still prints correctly.

Which currency the shop opens in ​

In order: the buyer's choice, then pbshop_currency, then the is_default row, then EUR as a last resort. pbshop_currencies lists the ones offered.

Entering prices ​

A product has a base currency and a price in it, on the main form. Prices in other currencies live in a grid on the product's Prices tab, one row per currency, which appears once the product has been saved.

A variant can carry its own price per currency the same way. Where it has none, the product's price applies.

Amounts are typed in the ordinary decimal form and converted to minor units on save; you do not type 1850 for €18.50.

The currency switcher ​

If more than one currency is published, the storefront shows a switcher. With one currency there is nothing to switch and nothing is drawn.

The choice lives in a cookie, not the session — and that is a cache question

PageBlocks' response cache keys on the address and on registered guest cookies, not on session state. A currency kept in the session would mean one guest's prices being served to another from the cache; in a cookie, a page in EUR is cached separately from the same page in USD.

If you are building your own storefront, read the choice through the switcher rather than inventing your own storage, or you will reintroduce exactly that bug.

The buyer's choice beats the shop's default, and the default remains the only answer for anyone who has not chosen.

Currencies and payment methods ​

A payment method lists the currencies it accepts; an empty list means any. A buyer is offered only methods that are published, accept the current currency, and are fully configured.

In the seed the Ukrainian gateways are bound to UAH, maib to MDL, EUR and USD, and Stripe and PayPal to nothing at all — those two work with dozens, and which ones depends on your contract, not on the gateway.

If no method accepts the current currency, there is nothing to pay with

The buyer is told, rather than shown an empty radio list. But it is worth checking after you add a currency: a shop that starts selling in PLN and forgets to add it to its gateway's method will take orders it cannot collect.

At the moment of payment the exponent is resolved strictly — an unknown currency raises rather than being guessed at 2 decimal places. Formatting a price on a card guesses; sending an amount to a gateway does not.

Gateways are sent the amount in whatever form each one wants: some take minor units, some take a decimal string with a dot. That translation is one function, not a habit repeated in ten drivers.

Next ​

  • Payments — binding currencies to methods
  • Promo codes — why a fixed discount is named per currency

pbShop — a shop component for PageBlocks