- A promotion threshold needs one amount per supported currency.
- Missing market values must block activation rather than fall back silently.
- Thresholds should use the same market price and tax rules customers see.
- Legacy promotions need an explicit migration path.
- This was project-specific work, not a feature we claim exists in standard Medusa.
The promotion rule the client could not express safely
The client needed campaign managers to decide both which basket amount counts—before or after tax, with or without shipping—and the threshold for every active currency. Copying one numeric threshold across markets would change the commercial offer. Converting it live would make the campaign move without an editorial decision.
We built a project-specific rule layer, backend endpoint and Admin widget around Medusa’s promotion model. Each cart is evaluated against the threshold chosen for its own currency, while the campaign team remains in control of the commercial offer in every market.
The business rule that breaks at the border
A merchant creates a promotion: spend at least €100 and receive 10% off. The shop also sells in pounds and Swiss francs. If the software stores only the number 100, should a British customer qualify at £100? That is not equivalent to €100. Should the checkout convert the cart back to euros using today’s rate? That can make eligibility move from one hour to the next and makes campaign reporting difficult.
The client needed the promotion itself to carry the intended threshold for every active currency: for example €100, £85 and CHF95. These amounts are commercial decisions, not necessarily live mathematical conversions. A campaign manager can choose market-appropriate values and know exactly what customers will see during the campaign.
Why one number creates real commercial risk
A threshold that is too low gives away margin. One that is too high makes a campaign ineffective or misleading. Silent fallback is especially dangerous: a newly opened market may inherit a number that looks valid but has the wrong currency meaning. The promotion appears configured while customers receive a materially different offer.
Taxes also affect the rule. Does ‘spend £85’ refer to the amount including VAT, excluding VAT, before discounts or after eligible discounts? Shipping and gift cards may or may not count. The answer must match the wording shown to customers. A multi-currency data structure cannot rescue an ambiguous promotion policy; it only gives that policy a place to be expressed.
What the campaign manager configures
The Admin interface lists every currency supported by the store and asks for a positive threshold in each one. A promotion cannot be enabled while a currency is missing. When the store adds a new currency, existing multi-currency promotions visibly become incomplete instead of pretending that a threshold exists.
The saved rule uses explicit currency codes and amounts in the smallest currency unit. This avoids decimal ambiguity and makes validation straightforward. The interface can show helpful reference conversions, but it should not silently replace the merchant’s chosen value when rates move. Promotion amounts normally remain stable for the campaign period unless someone deliberately edits them.
How the checkout decides whether the customer qualifies
At checkout, Medusa already knows the cart’s active market and currency. The promotion evaluator selects the threshold for that currency and compares it with the defined eligible cart amount. If the cart uses a currency absent from the rule, the promotion does not apply and the configuration error is reported. It does not borrow the euro number or guess a conversion.
The calculation should use the same price representation that customers see. Tax-inclusive markets, existing discounts, excluded products and returns all affect the meaning of the total. Boundary tests matter: one cent below the threshold, exactly equal and one cent above. A promotion that appears at £84.99 because two parts of the system round differently damages trust even when the monetary difference is tiny.
Keep the extension maintainable
This project-specific capability extended the promotion behaviour available in the Medusa version used for the build. The rule, configuration shape and automated checks were kept explicit so a framework upgrade could not silently change the campaign logic.
Customising a core promotion mechanism creates maintenance ownership. An upgrade test must fail loudly if the extension point changes, the business rule must remain documented and the team needs a migration path when the platform evolves. That turns the customisation into a durable asset rather than a hidden dependency.
How to introduce the rule without breaking old campaigns
Existing promotions may contain one numeric threshold. The importer or evaluator can continue reading that legacy form while new promotions use the currency map, but compatibility must be visible. Before rollout, inventory active campaigns and decide the correct value for each market. Do not generate values silently and call the migration complete.
A safe rollout evaluates representative carts with both old and new rules and reports differences before activation. Campaign owners review those differences, then publish deliberately. Once old promotions have ended or migrated, remove the compatibility path. Otherwise two meanings remain in the system indefinitely, and future teams cannot tell which rule an old campaign follows.
A promotion checklist for multi-market teams
For every campaign, define eligible amount, tax basis, treatment of existing discounts, products included, currency thresholds and rounding. Require a value for every active currency. Show configuration gaps in Admin and reject unknown currencies. Test cart changes, address changes, refunds, stacked promotions and exact threshold boundaries.
Also record whether the behaviour is native, configured or custom code. That helps the business understand maintenance risk. The core lesson is simple: currency is part of the rule, not decoration beside a number. Once that is explicit, campaign managers can make deliberate market decisions and the checkout can apply them consistently.
Common questions
Live conversion makes campaign eligibility move with exchange rates and may not match market strategy. Explicit amounts keep the offer stable and understandable.
Existing multi-currency promotions should be marked incomplete until a campaign owner supplies and approves the new threshold.
This article describes a project-specific extension found in a historical branch. It should not be presented as a native Medusa capability.