Appearance
Multicurrency
QuickBooks Desktop can run a company file with multicurrency turned on. This page explains how TenkeyBridge reads and writes currencies there, and where QuickBooks Desktop differs from QuickBooks Online. On a file with multicurrency off nothing changes: no currency fields appear on any record.
The developer sandbox company is single-currency, so none of this can be tried there. Test against a real company file with multicurrency on.
Currency codes and rates
- Currencies are ISO 4217 codes.
CurrencyRef.valueis always the code (CAD,EUR,USD), as in QuickBooks Online. QuickBooks Desktop identifies a currency by an internal list id; TenkeyBridge never returns that id in place of a code.CurrencyRef.nameis the currency's name in the company file. - Rates are plain numbers.
ExchangeRateis a float such as0.731234. TenkeyBridge sends up to 10 decimal places; a 6-decimal rate was confirmed stored exactly. It reads back as0.731234, never as a string. A rate must be positive. - Home amounts are read-only. Transactions in another currency carry
HomeTotalAmt(orHomeBalanceon invoices and credit memos), the amount in the home currency rounded to cents. It is ignored if you send it.
Every record on a multicurrency file carries a currency, including home-currency ones: a US company's ordinary invoice reads back with CurrencyRef USD and ExchangeRate 1.
Reading
Customers, vendors, accounts and transactions carry CurrencyRef; transactions also carry ExchangeRate and the home amount. To label them, TenkeyBridge reads the company file's currency list once and keeps it for 15 minutes. If that read fails, the request answers 502 CURRENCY_LOOKUP_FAILED rather than return an unlabelled currency. That includes the agent going offline or timing out during the lookup: on a read it surfaces as a 502, not a 503 or 504. Retry; nothing was changed.
Writing a transaction
Send CurrencyRef and, optionally, ExchangeRate:
json
{
"CustomerRef": { "value": "42" },
"CurrencyRef": { "value": "CAD" },
"ExchangeRate": 0.75,
"Line": [ ... ]
}- Omit
ExchangeRateand QuickBooks uses the currency's current list rate (for example 0.73 for CAD), and reads it back. - The currency comes from the customer or vendor, not from the transaction. On Invoice, SalesReceipt, CreditMemo, Estimate, Payment and RefundReceipt the customer decides; on Bill, VendorCredit, PurchaseOrder and BillPayment the vendor does. A
CurrencyRefthat differs from the customer's or vendor's currency is refused with400code2010("Invoice currency CAD does not match customer currency USD"). A matching one is accepted and not stored separately. A home-currency customer counts as the file's home currency (USD for a US company file). - Purchase (checks and card charges) takes its currency from the payee, then from the account when there is no payee. A payee and an account in different currencies are refused, with one allowance: a home-currency bank account may pay a vendor in another currency (QuickBooks stores the check in the vendor's currency).
- Deposit must use the currency of its
DepositToAccountRef. QuickBooks itself does not check this, so TenkeyBridge does; a mismatch is400code2010. SendDepositToAccountRefwithCurrencyRefon an update. - JournalEntry stores
CurrencyRefitself. QuickBooks refuses a foreign currency on an entry whose lines use only home-currency accounts, and a currency that differs from a foreign account on one of its lines. - RefundReceipt ignores
ExchangeRate. The refund check takes its currency from the customer and the rate is read back only. - A rate other than 1 on a home-currency transaction is refused (
400, code2010). - The currency must be active. QuickBooks keeps about 159 currencies, almost all inactive. An inactive currency on a customer, vendor, account, JournalEntry or Deposit is a
400; activate it first (see below). - An unknown code is
400code2010("Unknown currency code").
On an update, send CurrencyRef and ExchangeRate only when you are changing them; the customer, vendor or account that decides the currency must be in the body too (for example CustomerRef with CurrencyRef on an invoice update), or the update is a 400 that says which field to add. Changing only ExchangeRate is proven live on an invoice and on a JournalEntry. On BillPayment the rate is create-only. A rate of 1 on a home-currency transaction is accepted; any other rate there is 400.
BillPayment and the A/P account
A bill in a foreign currency is posted to a foreign A/P account, and a payment against it must name that account (APAccountRef) or QuickBooks cannot find the bill. When you create a BillPayment with a currency or rate and no APAccountRef, TenkeyBridge reads the A/P account of the one bill being paid and sends it. If the payment applies several bills, send APAccountRef yourself. A foreign-currency bill payment with APAccountRef and an ExchangeRate is proven live on create and reads back with both.
Customers, vendors and accounts
CurrencyRef on a Customer, Vendor or Account is written on create and stored; this is how a CAD customer or a EUR bank account is made. QuickBooks lets a customer's currency change only while the customer has no transactions; after that the update is refused (400, code 2500). A sparse vendor update that sends no currency leaves it unchanged (proven live). Changing a vendor's or account's currency on update is not proven live.
Accounts QuickBooks creates for you
The first time a foreign currency is used, QuickBooks creates accounts on its own: "Accounts Receivable - CAD", "Accounts Payable - EUR" and, on the first payment that settles at a different rate, "Exchange Gain or Loss". They appear in the account list like any other account. TenkeyBridge does not create or hide them.
Files with multicurrency off
A file with multicurrency off has only the home currency, so only the home-currency echo can be stored. A request that sends CurrencyRef USD or ExchangeRate 1 is accepted and the fields are dropped (QuickBooks has nowhere to put them), which lets code written for a multicurrency file run unchanged. Any other code or rate is 400 UNSUPPORTED_BY_DESKTOP. GET /companycurrency is an empty list, the keyed GET /exchangerate?sourcecurrencycode= is 400 UNSUPPORTED_BY_DESKTOP, and so is POST /companycurrency (turn multicurrency on in QuickBooks first).
Company currencies
GET /companycurrency lists every currency in the file, active or not. POST /companycurrency with Code (and optionally Name) is activate-or-add:
| The code is | Result |
|---|---|
| Known and inactive | Reactivated |
| Unknown to the file | Added (with no exchange rate until one is set in QuickBooks) |
| Known and already active | 400, code 6240 (duplicate) |
Code cannot be changed after creation. A sparse update can change Name and Active (send Active: false to deactivate). The currency list rate cannot be changed through the API.
Exchange rates
GET /exchangerate?sourcecurrencycode=CAD answers the current rate, with TargetCurrencyCode set to the home currency. The home currency answers a rate of 1. asofdate=YYYY-MM-DD is accepted; QuickBooks Desktop keeps only the latest rate for each currency, so a date before the stored AsOfDate is 400 UNSUPPORTED_BY_DESKTOP, and a date on or after it answers the stored rate. A code that is not in the file, or has no rate yet, is 400 code 610; a missing sourcecurrencycode is 400 code 2020.
Errors
| Situation | Response |
|---|---|
| Unknown or inactive currency, a currency that does not match its customer, vendor or account, or a bad rate | 400, code 2010 |
| Non-USD currency or non-1 rate on a file with multicurrency off | 400 UNSUPPORTED_BY_DESKTOP |
| Currency list could not be read, on a read | 502 CURRENCY_LOOKUP_FAILED |
| Currency check could not be read, before a write | 502 CURRENCY_LOOKUP_FAILED; nothing was written. If the agent is offline or times out, its own 503 or 504 instead; also nothing written |
| Write applied but its currency label could not be read | 502 CURRENCY_LOOKUP_FAILED; the write was applied, do not retry |
For per-entity detail see the entity matrix.

