Currency & FX handling

Multi-currency is a first-class concept in CargoSurge. This article covers the model, the rate sources, and the handful of edge cases that surprise people.

Overview

• Tenant base currency — defined at sign-up (home country's currency). Every report rolls up to this.
• Transaction currency — each quote, booking, invoice, and vendor bill carries its own currency. Can differ from base.
• FX rate — the conversion from transaction currency to base currency, locked at the moment the document is "issued" (quote sent, invoice issued, bill approved).

FX rate sources

Configure sources in Settings → Finance → FX Rates. Three modes:

1. Manual — you maintain rates yourself. Fastest to set up, least accurate over time.
2. Provider — automatic daily pull from an FX provider (ECB, OpenExchangeRates, FIXER). Free-tier providers cap at daily granularity; paid tiers offer intraday.
3. Central bank — specific countries have official exchange rates the tax authority uses for VAT. If you're in KSA or UAE you may need this mode.

CargoSurge picks the rate for a document by:

1. The tenant's current mode (manual vs provider).
2. The document's exchange_rate_date (defaults to today, but you can override on invoices that need back-dating).
3. Round to 6 decimal places.

When FX locks in

• Quotation: rate at the time of sending. If the quote is cloned months later, the clone pulls a fresh rate.
• Booking: inherits from the quote. Re-fetches only if you change the currency mid-booking.
• Invoice: locks at issued_at. From then on, payments against this invoice convert using this locked rate.
• Vendor Bill (AP): locks at received_at. Matches how the carrier invoiced you.
• Payment receipt: uses the rate on paid_at — which is typically different from the invoice rate. The difference is your FX gain / loss, booked to a dedicated ledger account.

Margin drift

A common surprise: you quote USD 1,000, the customer accepts three weeks later, the freight cost is EUR 900 on your vendor bill, and your reported margin shifts because the USD/EUR rate moved. That's real — not a platform bug.

CargoSurge surfaces this on the Booking detail page as:

• Planned margin — at quote time.
• Booked margin — at booking confirmation.
• Realized margin — at final invoice / vendor bill reconciliation.

A variance between these three is the signal. Big variances should prompt an FX hedge conversation if you're doing significant cross-currency volume.

Common pitfalls

Reverse-charge and place of supply

For UAE, KSA, and other VAT regimes, the tax treatment depends on where your customer is vs where supply happens. CargoSurge uses the tenant's home country + the customer's country to auto-pick:

• Standard-rated — VAT charged.
• Zero-rated — export / international freight.
• Reverse-charge — customer self-accounts for the VAT.

These determinations are auditable per invoice — see the invoice's detail view for the decision and its reasoning.

Per-charge tax rate

Every charge line can override the invoice-level tax rate. Use this when a single invoice mixes standard-rated domestic charges with zero-rated international freight.