agent currency conversion used a stale rate: invoices off by 2 percent for a week

Fixing "agent currency conversion used a stale rate: invoices off by 2 percent for a week"

TL;DR

Fetch the FX rate at invoice time, stamp it with a timestamp, and refuse to use any rate older than your max age (one hour is a sane default). Fail closed: if the rate fetch fails or the cached rate is stale, hold the invoice instead of billing on old math.

agent currency conversion used a stale rate: invoices off by 2 percent for a week

Steps

1. Change the invoicing flow to fetch the current rate from your rate provider immediately before computing the invoice total. Expected: Each invoice carries the rate and timestamp used.

2. Add a max-age check: reject any cached rate older than 60 minutes and fetch fresh. Expected: A week-old rate can never reach an invoice again.

3. Add a variance alert: compare each invoice's rate against the current spot rate daily and flag drift above your tolerance. Expected: Slow drift gets caught within a day, not a week.

4. Store the rate, source, and timestamp on the invoice record for audit. Expected: Any invoice's FX math is reproducible later.

Prevention

The bug is caching without expiry. Treat FX rates like milk: timestamped, short-lived, and discarded when old. If your provider supports billing in the customer's currency directly, prefer that over converting yourself.

Detection

Run a daily job comparing invoiced rates against the day's spot rate; flag anything beyond tolerance. Watch for customer complaints about totals that don't match the day's rate. Review invoices where the stored rate timestamp is far older than the invoice date.

Recovery

Identify every invoice billed with a stale rate. For overcharges, issue credit notes for the difference. For undercharges, decide per your policy whether to bill the shortfall or absorb it, then notify affected customers plainly. Fix the rate flow before the next billing run.

When this applies

• Multi-currency invoices differ from the day's rate by a noticeable percent
• The agent fetches FX rates on a schedule (or once) and reuses them
• Invoice records lack a rate timestamp

When it doesn't

• The provider does the conversion on payout and you bill in one currency (check the provider's rate, not yours)
• The contract fixes an exchange rate deliberately
• The drift is within normal intraday fluctuation and your tolerance

Compatibility

Stripe API (multi-currency amounts, automatic FX on some products), Adyen (multi-currency processing), PayPal REST API v2 (currency conversion on payments), plus FX rate sources like your treasury provider or a market data feed.

invoices billed with last week's exchange rate

FX rate cache never refreshed before invoicing

multi-currency totals drifted from the spot rate

Why it happens

Fetching a rate per invoice feels wasteful, so the agent fetches once and caches it. Nobody sets an expiry, the cache lives for the process lifetime, and a week later every invoice is priced on Monday's rate. Two percent is small enough per invoice to go unnoticed and large enough in aggregate to matter.

Edge cases

• Weekends and holidays: markets are closed but rates still move on Sunday open; decide whether to use Friday's close or hold
• Rounding: convert then round per line item, not on the total, and document which you do
• Hyper-volatile currencies: a 60-minute max age may be too loose; tighten it for volatile pairs

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3xHZY5A_UG6rxzR95-npQ