Changing a shop’s currency in one transaction.

Bulgaria adopted the euro on 1 January 2026. Re-denominating a live shop is a small piece of arithmetic wrapped in a large piece of care — here is where the money hides, and how we move all of it at once.

1 September 2026

9 min read

A shelf price label printed twice — the same price in leva above, in euro below.
From 1 January until 8 August 2026 every price in Bulgaria was written twice. For a shop whose prices are rows in a database, that was a migration.Illustration

Listen to this entry

0:00 / 12:33

Narrated by A I from the text of this page

For most of this year every price in Bulgaria was written twice. Shelf labels, menus, invoices, product pages — leva on one line, euro on the other — from the changeover on 1 January until the dual-display requirement lapsed on 8 August. For a business with printed labels that was a printing job. For one whose prices are rows in a database it was a migration, and a migration where the definition of a bug is a customer paying half, or twice, what they should.

The arithmetic takes an afternoon. Everything around it — the places money hides, the rounding rule, proving the result before a customer can see it — is the actual work, and it is the part that gets underestimated. The failures are quiet, too: nothing crashes, no alert fires, the shop simply starts selling at the wrong number until somebody notices.

So the rule we fix before writing a line of it is this: at every moment a customer can see the shop, the shop is entirely in the old currency or entirely in the new one. Nothing in between, not for a second. Almost every decision below follows from honouring that.

A currency change is not one column.

The instinct is a single statement: UPDATE products SET price = price / 1.95583. It is wrong twice over. It assumes prices live in one place, and it treats rounding as something that happens to you rather than something you decide.

Money hides. In the catalogue, obviously, and in the compare-at price beside it. But also in every scheduled discount rule, each with its own amount and its own floor. In the free-delivery threshold and the per-kilometre rate behind it. In the instalment schemes quoted from a lender. In the order history. In the e-mail templates that print a total. In the product feeds. In the analytics events. In the structured data a crawler read last week. In the copy on a service page, where somebody once typed a number into a sentence.

Once the list exists it sorts itself into three kinds of number — and only the first is the kind everybody plans for.

  • 01Values you convert. Live prices, discount amounts, thresholds, rates — every number a customer will be quoted from now on.
  • 02Values you must never convert. The order history. An order placed in leva was placed in leva; rewriting its total so a report looks tidy destroys the only record of what actually happened.
  • 03Values you re-derive rather than convert. Anything computed from a price: basket totals, instalment schedules, feed entries, cached pages. Converting a derived number instead of recomputing it is how a total stops matching its own lines.
One price at the centre, connected outward to the catalogue, discount rules, delivery thresholds, instalment schemes, order history, e-mail templates, product feeds, analytics events and structured data. Only the order history is drawn dashed: it is the one that is never converted.
Fig. 01
The catalogue is the one everybody plans for. The e-mail template that prints a total, and the number somebody once typed into a sentence, are the ones that bite.Diagram

Rounding is a decision, not a detail.

The rate is not a market rate and never was: one euro is 1.95583 leva, fixed, and the conversion rules are explicit about how to use it. Divide by the full rate. Never multiply by an inverted one. Round to the nearest cent. Almost nothing comes out clean — a 1,999 lv item is €1,022.0725, and the moment you write €1,022.07 you have made a decision that now has to be made identically everywhere else.

So the rounding rule is written once and imported everywhere: by the migration, the checkout, the feed generator, the instalment calculator. Two rounding implementations in one codebase is a bug with a delay fuse — they agree on almost every number, and disagree on the one a customer complains about.

The other half of the decision is where rounding happens. The sum of rounded lines is not the rounded sum; a three-item basket converted line by line can differ from the same basket converted at the total, by a cent. Pick which one is authoritative and derive the other from it. We pick the line, because the line is the number printed on the product page — and a total that does not equal what the customer just read is not a rounding difference to them, it is a shop that changed its mind.

Prices are also chosen, not just calculated. 1,999 lv was chosen by somebody; €1,022.07 was chosen by arithmetic. The temptation is to tidy it to €1,029 while you are in there, and it should be resisted: a release that both converts and re-prices cannot be audited, because there is no original left to check the result against. Convert exactly, verify to the cent, then re-price deliberately in a separate, boring release the week after.

1,999 leva divided by 1.95583 giving 1,022.0725 euro and rounded to 1,022.07, beside a three-line basket where the sum of the rounded lines and the rounded sum differ by one cent.
Fig. 02
Round once, in one place, and decide whether the line or the total is authoritative. A total that does not match what the customer just read is not a rounding difference to them.Diagram

Everything, or nothing.

We run the re-denomination as a single database transaction. Postgres gives you all-or-nothing for free, provided you keep the whole change inside one transaction and stay disciplined about keeping everything else out of it. No e-mails, no calls to a payment provider, no file writes, no cache purges from inside: none of those roll back, and a transaction that has already sent a customer an e-mail is not atomic any more, whatever the database believes.

Before it writes a single new number, the migration copies every row it is about to touch into audit tables, with the rate and the timestamp. They cost almost nothing and answer the only question anyone asks afterwards, sometimes months later: what was this before?

Then, still inside the transaction, the assertions — a couple of dozen of them. Not a verification script for afterwards; statements that run before the commit and abort it:

  • 01Every converted price, multiplied back by the rate, reproduces its original to the cent.
  • 02Row counts are identical before and after; nothing was created or lost on the way.
  • 03No price is null, zero or negative — the classic shape of a division that met a bad row.
  • 04No discount is larger than the price it discounts.
  • 05Zero rows changed in the order history: the past is read-only, and the assertion proves it rather than assuming it.
  • 06Every row now marked in the new currency carries a plausible number for it, and every row deliberately left in the old one is exactly what it was.
A single transaction drawn as a gate: begin, copy every affected row into audit tables, convert, run the assertions, and then either commit or abort back to the starting state.
Fig. 03
Everything that cannot be rolled back — e-mails, payment calls, cache purges — stays outside the gate. Inside it, the assertions still have the power to say no.Diagram

A check that runs after the commit can only tell you what went wrong. A check that runs before it can still say no.

Idempotent, and proved twice.

Migrations get run more than once. A deploy retries. A job times out and something restarts it. Somebody runs it in the terminal they thought was staging. With most migrations that is loud — a duplicate key, a missing column, an error you cannot miss. With a re-denomination it is silent: a price divided by the rate twice is not an error, it is about €522 on an item that costs €1,022, and every system downstream will accept it politely.

So the migration writes down that it has run — the rate, the timestamp, the counts — and refuses to touch a database already carrying that marker. The guard commits in the same transaction as the work it guards, because a guard that can be written without the change, or the change without the guard, protects nothing.

Then we run the whole thing twice against a copy of production and diff the result. The second run must change nothing. That is the only version of this claim worth making: an idempotency guard nobody has actually run twice is a comment, not a guarantee.

The same price divided by the rate twice — 1,999 leva to 1,022.07 euro, then to 522.58 euro — with no error raised at either step.
Fig. 04
Run most migrations twice and something breaks loudly. Run a re-denomination twice and the price simply halves again, and every system downstream accepts it politely.Diagram

The things that quote a price.

The transaction is the small part. Everything that has memorised a number has to move in the same release, or the shop spends an afternoon telling different stories in different places.

  • 01Product feeds. Shopping feeds and price-comparison sites take a currency attribute. A feed still declaring the old currency gets the shop’s prices compared with everyone else’s at roughly twice their value.
  • 02Financing. Instalments quoted live through a lender’s API: the amount you send and the schedule you display have to switch in the same deploy, or the monthly figure on the product page stops matching the contract.
  • 03Transactional e-mail. Every template that prints a total — and the confirmation e-mail is the document the customer keeps.
  • 04Analytics. E-commerce events carry a currency, and two currencies in one property make a quarter’s revenue meaningless. The migration is a reporting boundary, and worth annotating as one.
  • 05Exports. Order exports now span both currencies, so the currency has to print per order — never once, in the header.
  • 06Structured data. Product and Offer markup carries priceCurrency, and a crawler will happily serve the old one in search results for weeks after the page itself is right.

The cache nobody controls.

Our own caches regenerate. Static pages rebuild, the CDN is purged, the pages that refresh hourly pick the new numbers up on their own. The caches we do not control are the ones in visitors’ browsers: a returning customer holding yesterday’s catalogue, or yesterday’s basket, meeting a checkout that has moved on without them.

So every local cache we keep in a browser is versioned, and the version is part of the key. Bump it and every stale copy, in every browser, is discarded on the next load. That rule goes into a build long before there is a currency to migrate, for entirely unrelated reasons, and then pays for itself in a single release. Most of the good decisions in a long-running codebase are like that — cheap when they are made, and only obviously right years later.

What we would tell anyone doing this.

Bulgaria will not do this again. But the shape of the problem — one value that lives in forty places and has to change in all of them at once — turns up in any platform that runs long enough: a VAT change, a rename, a switch of units, a tenant split. What we carry into the next one:

  • 01Inventory the money before you estimate. Every column that stores an amount, every constant in the code, every template that prints one. The list is always longer than the guess, and what you miss is never the catalogue.
  • 02Store money as integer minor units, or at worst a fixed-precision numeric. If prices are floats, fix that first, in its own release — you cannot verify to the cent what was never accurate to the cent.
  • 03Put the currency on the row. A shop that cannot say which currency an order was placed in has lost its own history, and no conversion rate gives it back.
  • 04Convert exactly; re-price later. Two changes in one release cannot be audited separately, and the one you cannot audit is the one that moves money.
  • 05Take the maintenance window. The transaction runs in seconds. An announced hour of downtime is cheaper than a single order placed against a half-migrated catalogue, and far cheaper than the conversation afterwards.
  • 06Write the rollback first, and run it. Not the plan for the rollback — the rollback. A restore nobody has performed is a hope with a filename.

Doing it once, correctly.

None of this is exotic. It is one transaction, a set of assertions with the power to undo the change, a guard that has actually been run twice, and a release that moves everything quoting a price at the same moment. What makes it hard is that all of it has to be decided before the migration is written; none of it can be added afterwards, and none of it is visible in the demo.

That is the difference between a change that happens once and a change a customer discovers for you. If your platform is facing one of this shape, send us a brief.

— End of article 01

Engineering

¶ — Newsletter

Stay in touch.

Get an email when we publish something new from the studio. No spam.

Subscribe

Email only

No spam · Unsubscribe anytime · Privacy policy