Multi-Currency

Hydra supports selling in multiple currencies from a single project. Prices are stored in your base currency and automatically converted at checkout using daily exchange rates.

How it works

Base currency — set when you create your project (e.g. USD). All variant prices and order totals are stored in this currency as integers in the smallest unit (cents).
Enabled currencies — additional currencies your storefront can display and accept. Managed via the Store API.
Exchange rates — updated daily from live foreign exchange data. You can also set manual overrides via the Exchange Rates API.
Conversion margin — an optional percentage markup applied on top of the exchange rate (e.g. 2.5 adds 2.5% to converted prices).
Rounding — controls how converted prices are rounded for display.

Configuring currencies

Set enabled currencies

curl -X PATCH https://api.hydrajs.dev/v1/store \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled_currencies": ["USD", "EUR", "GBP", "CAD"],
    "currency_conversion_margin": 2.0,
    "currency_rounding": "0.99"
  }'

Rounding options

Value	Description	Example (€12.34)
`none`	No rounding (exact conversion)	€12.34
`1`	Round to nearest whole unit	€12.00
`0.99`	Round up to nearest `.99`	€12.99
`0.95`	Round up to nearest `.95`	€12.95
`0.50`	Round to nearest `.50`	€12.50

Exchange rates

Exchange rates are fetched automatically each day. The current rates for your project are available via the API:

curl https://api.hydrajs.dev/v1/exchange-rates \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

{
	"data": {
		"base": "USD",
		"rates": {
			"EUR": 0.9234,
			"GBP": 0.7891,
			"CAD": 1.3612
		},
		"updated_at": "2026-09-06T03:00:00.000Z"
	}
}

Manual overrides

To lock a specific rate (e.g. for a promotional price guarantee), set it manually:

curl -X PUT https://api.hydrajs.dev/v1/exchange-rates/EUR \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate": 0.95}'

Manual overrides persist until you remove them. The daily auto-update skips currencies with manual overrides.

Price tiers (Price Keys)

For direct per-currency pricing (instead of conversion), use Price Keys with the Variant Prices API. This lets you set exact prices for each currency or customer tier (wholesale, VIP) without relying on conversion.

# Set a specific EUR price for a variant
curl -X PUT https://api.hydrajs.dev/v1/variants/var_abc123/prices/wholesale \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1999, "currency": "EUR"}'

Checkout and orders

When a customer checks out in a non-base currency:

The cart total is converted using the current exchange rate + margin
The converted amount is charged via the payment provider
The order records both the presentment currency (what the customer paid) and the base currency (for your accounting)
Refunds are issued in the presentment currency at the original conversion rate

Storefront integration

Use the currency query parameter on product and cart endpoints to get prices in the customer’s preferred currency:

# Get products with EUR prices
curl "https://api.hydrajs.dev/v1/products?currency=EUR" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

The response includes converted prices alongside the base currency values.

All amounts are integers

Hydra stores all monetary values as integers in the smallest currency unit (cents for USD/EUR, pence for GBP, etc.). This avoids floating-point rounding errors.

Display price	Stored value	Currency
$19.99	`1999`	USD
€14.50	`1450`	EUR
¥1500	`1500`	JPY

For zero-decimal currencies like JPY, the stored value equals the display value.

Best practices

Set a conversion margin to absorb exchange rate fluctuations between conversion and settlement.
Use price keys for important markets. Automatic conversion is convenient, but strategic markets deserve hand-set prices.
Monitor exchange rates. Use the Exchange Rates API to check when rates were last updated and set manual overrides if needed.
Display the currency code. Always show the ISO 4217 code (USD, EUR) alongside the amount so customers know which currency they’re paying in.