Diamond Stone: US dollars and other currencies
Date: 2026-11-11. Revision 1. Screens in docs/ui-shell-mockup.html, section "US dollars
and other currencies"; flow in docs/system-flows.html.
Many customers, most suppliers abroad and almost all sea freight deal in US dollars. Until now the plan said only "rials, with USD and AED" and one month-end entry. This document plans it through every module.
This is a plan, not accounting or tax advice. Section 11 lists what the accountant and tax adviser must confirm. Rates and bank practice here are from general knowledge and were not checked at a source today.
1. What was planned before, and what was missing
| Was planned | Was missing |
|---|---|
| The books are kept in rials, three decimals | How a quote, order, invoice or bill is held in another currency |
| "USD and AED for export and imports" | Which rate is used, when, who sets it, and what locks it |
| A month-end revaluation entry | Receipts that arrive short after bank charges; payment in a different currency from the invoice |
| "Currencies and rates" as an undrawn screen | Bank accounts and bank details per currency on documents |
| A Money field "with rate" | How amounts in two currencies are shown without being confused or added together |
| The tax invoice shows VAT in rials | Advances, landed cost, approval limits, credit limits, reports and the portal in more than one currency |
2. The one fact that makes dollars simple here
The rial is pegged to the US dollar, at about 1 rial = 2.6008 dollars, or 0.3845 rials per dollar, and has been for decades. The UAE dirham is also pegged to the dollar. So for dollars and dirhams the rate does not move from day to day. What remains is small: the bank's margin between buying and selling, and transfer charges.
That lets the plan be simple for dollars without being wrong for anything else:
- Rates are data, never fixed in code. A pegged pair is one rate "in force from" a date until someone changes it. A floating currency (the euro, for Italian suppliers) has a rate per day.
- The same rules run for all currencies. Dollars simply produce very small differences.
3. Rules
- Every amount carries its currency. There is no amount without one, anywhere in the data or on screen.
- A record stays in the currency it was made in: quote, order, proforma, invoice, receipt, supplier order, bill. The customer deals in one currency from first quote to last statement.
- The books are in rials. Each foreign amount is also stored in rials at the rate of its date, with that rate beside it.
- The rate is locked on the record. A later change of rate never changes a quote already sent or an invoice already issued.
- Amounts in different currencies are never added. A total across currencies is shown in rials and says so.
- The customer sees only their own currency. Staff see both.
- Each currency has its own number of decimals: rials three, dollars, dirhams and euros two. Held as data, so a currency with none or three can be added.
- Limits and floors are set in rials (approval limits, credit, margin floor) and compared after conversion, so a dollar deal cannot slip under a rial limit.
4. Three rates, and who owns each
| Rate | Used for | Set by | For dollars |
|---|---|---|---|
| Company rate | Quotes, orders, bills, everyday conversion, the figure staff see beside a foreign amount | The accountant; a change needs the owner | One fixed rate. Proposed 0.3845 |
| Tax rate | The rial value of VAT on an invoice in another currency | Read from the source the tax rules name (reported to be the Central Bank's rate; to confirm) | The same in practice |
| Bank rate | What the bank actually gave when money was converted | Comes from the bank statement; never typed in advance | Slightly worse than the peg |
For a floating currency the company rate is fetched each morning from one source (to choose), or entered by the accountant if the source fails. A missing rate for a date stops the posting and asks; nothing is guessed. A sent quote in a floating currency raises a Halo ring if the rate has moved more than a set amount since it was sent.
5. Selling in dollars
| Step | What happens |
|---|---|
| The customer | Has a currency on their record, set when they are created (rials by default; dollars proposed for any customer outside Oman). Changing it later affects new quotes only |
| Prices | Held in rials. A dollar quote converts each price at the company rate and rounds to the cent. A separate dollar price list is possible later as a setting; with the peg it gains little |
| The quote | Made in the customer's currency. Sales may switch it before sending. The rate is stored on it. Staff see the rial value and the margin in rials beneath |
| Changing currency after sending | Not possible. A new version of the quote is made |
| Approval | The owner sees the dollar amount as the customer will, and the rial value and margin. The limit is checked in rials |
| Proforma and invoice | In dollars, with the dollar bank account's details (section 8). Amount in words in dollars. For a sale that carries VAT, the VAT is shown in rials with the rate used, as the tax rules require |
| The portal | Everything in dollars. No rial figures |
| The advance | Arrives in the dollar account and is recorded in dollars, and in rials at that day's rate |
| Credit limit | Held in rials; the customer's open dollar balance is converted to compare |
| Statement | In dollars |
When the payment arrives
International transfers rarely arrive as the exact invoice amount.
| What arrives | What the system does |
|---|---|
| The exact amount | Matches it |
| A little less, because banks along the way took fees | If the shortfall is within the tolerance (proposed: 35 dollars or 0.5 %, whichever is less), it proposes: receipt for the amount received, the rest to bank charges, invoice paid. The accountant accepts. Above the tolerance, the balance stays open and the customer is told |
| A different currency (invoiced in dollars, paid in dirhams or rials) | Matched at the bank's rate for that day; the difference goes to exchange differences |
| Dollars, but the company has no dollar account | The bank converts on arrival. The receipt is recorded at the bank's rate and the difference from the invoice's rate goes to exchange differences |
| More than invoiced | Held as the customer's credit in their currency |
The default terms of sale say that all bank charges are the buyer's
(docs/DOCUMENTS.md section 6). The tolerance exists because that clause is not worth
enforcing for a few dollars.
6. Buying, freight and landed cost
| Matter | Rule |
|---|---|
| Supplier | Has a currency, like a customer |
| Supplier order and bill | In the supplier's currency, rate stored on each |
| Advance to a supplier | Kept at the rate on the day it was paid. It is not revalued (it is a right to goods, not money owed) |
| Sea freight, port and line charges | Usually quoted and billed in dollars; entered as such |
| Customs duty | In rials, on the value customs works out at its own rate. That rate is entered from the customs declaration, not assumed |
| Landed cost | Always in rials: stone at the rates it was actually paid or billed, plus freight, insurance, duty and clearing, shared across the slabs. The screen shows each part in its own currency and in rials |
| Back-to-back orders | Often dollars on both sides. The margin is shown in dollars for the deal and in rials for the books |
| Paying a supplier | From the dollar account where there is one. The payment run groups by currency and by account; whoever prepares still cannot release |
| Letters of credit | In dollars. The documents are produced in the credit's currency with its exact wording |
7. In the books
Under IFRS for SMEs (the section on foreign currency), as the accountant will confirm:
| Event | Treatment | Entry |
|---|---|---|
| Any foreign invoice, bill, receipt or payment | Recorded in rials at the rate on its date | As the normal entry, in rials |
| An invoice settled at a different rate from the one it was booked at | The difference is a gain or loss | Dr or Cr Exchange differences (realised) |
| A short receipt within tolerance | A cost | Dr Bank charges · Cr Receivable |
| Month end: money owed to us or by us, and foreign bank balances | Restated at the month-end rate | Dr or Cr Exchange differences (unrealised) |
| Month end: stock, advances paid and received, fixed assets | Not restated; they stay at their original rate | None |
| Conversion rounding (two decimals against three) | To a rounding account, in baisa | Dr or Cr Rounding |
For dollars and dirhams the month-end entry is close to nothing while the peg holds. It is still run, because the euro and others do move, and because an auditor expects the step.
Reports. Money owed to us and by us, by age, per currency and in rials. Cash by currency and account. Exchange differences for the period, realised and unrealised. A schedule of balances in foreign currency for the audit pack. Every management figure is in rials; tapping it shows the split by currency.
8. Bank accounts and bank details
- Each bank account has one currency. Proposed: a rial account and a dollar account at least.
- A document shows the bank details that match its currency: a dollar invoice shows the dollar account, with its SWIFT code, IBAN and any intermediary bank. The rule is automatic; nobody picks an account when sending.
- Every account's details are under the same control as before: a change needs a second person and a waiting period, and the public check page shows the right account for that document.
- Bank matching is done per account, in that account's currency.
9. How money is shown
| Where | Rule |
|---|---|
| Format | 3,250.00 USD and 1,249.625 OMR: the figure, then the code, smaller and muted. Codes, not symbols: "$" is used by many currencies |
| A foreign amount, to staff | The amount in its currency; beneath it, smaller, ≈ 1,249.625 OMR. In a tight list, the foreign amount alone with its code |
| A foreign amount, to the customer | Their currency only |
| Telling them apart | The code is always present. An amount not in rials also carries a small tinted currency mark, so 3,250 dollars is never read as 3,250 rials (a mistake of 2.6 times) |
| Totals and dashboards | In rials. "Includes 3 in USD" opens the split |
| Entering money | The Money field has the currency beside the amount, taken from the record. As the person types, the rial value shows beneath. Changing the rate by hand needs permission and a reason |
| Review before posting | Both currencies and the rate are shown in full |
| The Omnibar's action | Names the amount in the record's currency: "Approve 3,250.00 USD" |
| Search | "3250 usd" answers with the rial value at the company rate |
| Arabic | Western digits; the code stays in Latin letters; the amount is kept left to right |
| Amount in words on documents | In the document's currency, in both languages |
10. Module by module
| Module | Change |
|---|---|
| Customers, suppliers | A currency on each. Default by country |
| Catalogue and prices | Prices in rials; shown converted for a foreign-currency customer. A buffer per floating currency (none for dollars) |
| Quotes, orders | Currency and rate on each; margin always worked out in rials |
| Approvals | Both amounts shown; limits in rials |
| Portal | The customer's currency throughout |
| Documents | Currency, rate where tax needs it, matching bank details, amount in words. The commercial invoice and packing list for export in the sale's currency |
| E-invoicing (2027) | The format carries the document currency, rials as the tax currency, and the rate. Already held |
| Purchasing and shipping | Supplier currency; freight in dollars; landed cost in rials |
| Money | Section 7; bank accounts per currency; payment runs per currency |
| Store (samples) | Rials. A visitor abroad may be shown a dollar estimate; the charge is in rials. A setting |
| Website | No prices, as before. Calculators that show a cost take the visitor's currency as an estimate only |
| HR | Pay is in rials. A travel expense in another currency is claimed in that currency and converted at the receipt's or card's actual rate |
| Inbox and AI | The document reader must find the currency on a bill and never assume rials; a bill with no readable currency is flagged. Drafted replies quote in the customer's currency |
| Halo | A sent quote whose floating rate has moved; a receipt that arrived short; a missing rate. A figure shortcut may show a rate |
| Reports | In rials, with the split |
11. Settings
Under Control → Money → Currencies.
| Setting | Default |
|---|---|
| Currencies in use | OMR, USD, AED. Others are added with their decimals |
| Company rate for each pegged currency | USD 0.3845; AED from the two pegs. Each "in force from" a date |
| Rate source for floating currencies | To choose; the accountant enters by hand until then |
| Who may change a rate; who approves | Accountant; owner |
| Who may change a rate on one record, and the reason required | Accountant only |
| Default currency for a new customer or supplier | By country: rials in Oman, dollars elsewhere |
| Prices for foreign-currency customers | Converted from rials; rounded to the cent |
| Buffer on floating currencies | 2 % |
| Alert when a sent quote's rate has moved | 1 % |
| Short-receipt tolerance | The lesser of 35 USD and 0.5 % |
| Bank account for each currency, shown on documents | Chosen once per currency |
| Month-end revaluation | Automatic step in the close; the accountant reviews |
| Show the rial value to staff beside foreign amounts | On |
| Store: show a dollar estimate to visitors abroad | Off |
12. For the accountant and tax adviser
- That the books are in rials, and the treatment in section 7.
- The rate to use for dollars: the peg figure, or the bank's.
- The rate source the tax rules require for VAT on a foreign-currency invoice, and how it must be printed.
- Revenue where an advance was received at one rate and the balance at another.
- Whether the month-end restatement is reversed the next day or carried.
- Which account takes short receipts: bank charges, or a discount.
- Landed cost: which rate values stone paid partly in advance and partly on the bill.
- The rate customs uses, and where it is recorded.
13. Decisions for the owner
- Which currencies at the start. Proposed: rials, dollars, dirhams; euros when the first supplier needs them.
- Whether there is, or will be, a dollar bank account. It decides whether dollar receipts are converted on arrival.
- Dollars by default for every customer outside Oman. Proposed: yes.
- The tolerance for short receipts. Proposed: 35 dollars or 0.5 %.
- Prices converted from rials, or a separate dollar price list. Proposed: converted.
- Whether customers in Oman may be quoted in dollars (project buyers sometimes ask). Proposed: yes, with VAT shown in rials.
14. Mistakes this guards against
| Mistake | Guard |
|---|---|
| A dollar figure read as rials, or the reverse | The code on every amount; a currency mark on anything not in rials; both shown at review and approval |
| Adding dollars to rials in a total | Refused by the rules library; totals are in rials |
| A rate changed and old quotes silently repriced | The rate is locked on each record |
| A rate typed wrongly (0.3485 for 0.3845) | A rate more than 1 % from the last one for a pegged pair is refused without the owner |
| A dollar invoice sent with the rial account's details | Bank details follow the document's currency automatically |
| A short receipt left open for months over a few dollars | The tolerance and a proposed entry |
| A deal approved under the rial limit because it was in dollars | Limits compared in rials |
| A bill read by the document reader with the wrong currency | The currency is a required, checked field; the supplier's usual currency is compared |
| The peg assumed forever | Rates are data with dates; nothing in the code knows the number |
Samples in dirhams and riyals (added 11 November 2026)
To be listed as products in the UAE and Saudi Arabia, samples would need prices in
those currencies on their own addresses. This would change the default "samples in
rials" above; it is a decision in docs/WEBSITE.md section 20.