Live Exchange Rates

Paid pluginsize Splanned, not built

Indicative price, not an offer: €4.99-9.99/mo — owns the support commitment (daily ECB/OANDA updates, freshness guarantee)

Generated from docs/plan/paid/live-exchange-rates/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module that pulls daily exchange rates from ECB or OANDA and keeps multi-currency pricing fresh without merchant intervention. The system guarantees rates are updated by 08:00 UTC daily, surfaces rate timestamp in admin, and alerts merchants when a rate fetch fails.

The problem

A merchant’s static EUR→CHF rate is 1.05 today but 1.02 in three days; they manually update it and miss the last day, losing margin to arbitrage. Without daily automation, maintaining accurate rates across 5+ currencies becomes labor-intensive and error-prone.

What it does

• Daily cron job fetches ECB historical rates (via public API, no auth required) or OANDA spot rates (merchant provides API key for premium freshness)
• Store exchange rate history: { date, from_currency, to_currency, rate_per_unit } in audit-trail table
• Compute derived rates (if USD→EUR and EUR→GBP exist, derive USD→GBP) to fill sparse currency pairs
• Alert merchant via email/webhook if rate fetch fails (circuit-breaker: if two consecutive fails, disable auto-update and notify)
• Display ‘rates last updated at 08:15 UTC’ timestamp in admin pricing UI
• Storefront can request prices in any currency that has a rate within last 24 hours; return rates.updated_at to client
• Provide rate_timestamp in cart/checkout API so storefront can display ‘prices locked as of HH:MM UTC’
• Scheduler integration: runs at 08:00 UTC daily, logs rate fetch success/failure to audit trail

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Manual rate override (merchants on ECB plan cannot edit rates; this is the core value — no daily manual work)
• Per-customer currency pricing (e.g., VIP customers get better rates; see loyalty-points-vip-tiers-rewards)
• Real-time rate updates (daily is the SLA; live rates are a different product tier)
• Crypto or commodity price feeds (ECB + OANDA are fiat-only; crypto is out-of-scope for liability reasons)

Data model

Add exchange_rates table: { date, from_currency, to_currency, rate_per_unit, source, fetched_at }. Add shop settings: rate_source (‘ecb’, ‘oanda’), oanda_api_key (encrypted), rate_fetch_enabled, rate_last_success. No migration needed if added as new table. Historical rates are kept forever for audit.

API

• GET /admin/settings/exchange-rates — read current rate source and last fetch timestamp
• PUT /admin/settings/exchange-rates — update rate source or API key (update triggers immediate fetch)
• GET /admin/exchange-rates/history?from=2024-09-01&to=2024-09-30 — audit rate changes over time
• POST /webhook/rate-update (internal) — called by scheduler with new rates

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Add ‘Exchange Rates’ card in Settings > Pricing. Radio buttons: ‘ECB (free, daily UTC 08:00)’ or ‘OANDA (live, requires API key)’. Show ‘Rates updated at 08:15 UTC on 2024-09-03’ with a refresh button (triggers immediate fetch). List current rates (USD/EUR = 1.0845, GBP/EUR = 1.1653, etc.) with source and age. Show alert banner if last two fetches failed.

The seam — why this is paid

Paid module owns the operational burden: pulling live rates, freshness SLA, managing third-party credentials (OANDA), and support for rate fetch failures. Core owns the multi-currency price structure; this module builds on it. Merchants without this module can set rates manually via core multi-currency-pricing-engine (static, requiring edit).

a paid pack owns the support commitment — we pull live rates daily, guarantee freshness, and absorb the operational burden.

Dependencies

• multi-currency-pricing-engine (this module adds rates to that foundation)
• Scheduler/cron system (must be able to run daily job)
• Settings system (to store rate_source, api_key securely)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• ECB rates are fetched at 08:00 UTC daily; current rate for EUR→USD is recorded to exchange_rates table
• If a fetch fails (network error, API downtime), second fetch is retried at 09:00 UTC; if both fail, email alert is sent to shop owner
• A derived rate EUR→GBP (via USD) is computed if direct rate is missing
• Storefront receives rate_timestamp in checkout API; timestamp is within 36 hours of current time or prices are marked ‘stale’
• Manual rate override is NOT available (no field in admin; customer cannot edit rates even if OANDA key is set)
• Merchant can switch from ECB to OANDA and back without losing historical rate data

Risks

If rate fetch uses insecure HTTP instead of HTTPS for OANDA, API key is exposed in logs. If derived rates are cached and not recomputed hourly, sparse currency pairs become stale. If rate timestamp is wrong (server timezone vs UTC), checkout displays incorrect staleness. If merchant can manually override rates, the ‘hands-off’ value is destroyed and support burden increases.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.