Hydra is now in beta|Get started free|Follow our journey on X.com

Exchange Rates API
On this page

Exchange Rates

Hydra supports multi-currency pricing via exchange rates fetched from Stripe’s FX API. Rates are cached in the database and automatically refreshed by a daily cron job at 03:00 UTC. You can also trigger a manual refresh at any time.

Base URL: https://api.hydrajs.dev

Auth: All exchange rate endpoints require a secret key (sk_live_* or sk_test_*).

Endpoints

Method Path Auth Description
GET /v1/exchange-rates Secret List exchange rates
POST /v1/exchange-rates/refresh Secret Refresh rates from FX provider

List exchange rates

GET /v1/exchange-rates

Returns the current exchange rates for all enabled currencies relative to the store’s base currency. Only currencies configured in the store’s enabled_currencies setting are included. The base currency itself is omitted (a base-to-base rate is always 1).

Query parameters

Parameter Type Default Description
fields string - Comma-separated fields to return

Request

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

Response 200

{
	"data": [
		{
			"base_currency": "USD",
			"target_currency": "EUR",
			"rate": 0.9234,
			"source": "builtin",
			"fetched_at": "2026-08-17T03:00:00Z"
		},
		{
			"base_currency": "USD",
			"target_currency": "GBP",
			"rate": 0.7891,
			"source": "builtin",
			"fetched_at": "2026-08-17T03:00:00Z"
		},
		{
			"base_currency": "USD",
			"target_currency": "CAD",
			"rate": 1.3612,
			"source": "builtin",
			"fetched_at": "2026-08-17T03:00:00Z"
		},
		{
			"base_currency": "USD",
			"target_currency": "MXN",
			"rate": 17.245,
			"source": "builtin",
			"fetched_at": "2026-08-17T03:00:00Z"
		}
	]
}

ℹBase currency

Rates are relative to the store’s base currency. If your store’s base currency is USD, all rates represent how many units of the target currency equal 1 USD. For example, a rate of 0.9234 for EUR means 1 USD = 0.9234 EUR.

Refresh exchange rates

POST /v1/exchange-rates/refresh

Fetches the latest exchange rates from Stripe’s FX Quotes API and updates the cached values. Each target currency is fetched individually and upserted. A history entry is recorded for audit purposes.

⚠Stripe API key required

This endpoint requires a valid STRIPE_SECRET_KEY configured in your environment. The Stripe FX Quotes API is used under the hood.

Request

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

Response 200

{
	"data": {
		"rates_updated": 4,
		"rates": [
			{
				"base_currency": "USD",
				"target_currency": "EUR",
				"rate": 0.9241,
				"previous_rate": 0.9234
			},
			{
				"base_currency": "USD",
				"target_currency": "GBP",
				"rate": 0.7895,
				"previous_rate": 0.7891
			},
			{
				"base_currency": "USD",
				"target_currency": "CAD",
				"rate": 1.3598,
				"previous_rate": 1.3612
			},
			{
				"base_currency": "USD",
				"target_currency": "MXN",
				"rate": 17.198,
				"previous_rate": 17.245
			}
		]
	}
}

The previous_rate field shows the rate before the refresh, or null if this is the first time a rate has been fetched for that currency pair.

ℹAutomatic refresh

A daily cron job refreshes exchange rates automatically at 03:00 UTC. Manual refresh is available for immediate updates, such as after enabling a new currency. The refresh response includes previous_rate so you can see how rates have changed.

The exchange rate object

Field Type Description
base_currency string 3-letter ISO currency code of the store’s base currency (e.g. USD)
target_currency string 3-letter ISO currency code of the target currency (e.g. EUR)
rate number Exchange rate (decimal). Multiply base amount by this to get target amount
source string Rate source (currently always builtin)
fetched_at string ISO 8601 timestamp of when the rate was last fetched