Using the multicurrency feature with the sdk

This page is a brief overview the QuickBooks multicurrency feature from the perspective of the SDK. We’ll cover the multicurrency impact on company preferences, transactions, list objects and reports. For more information on how this feature works, please consult the QuickBooks in-product help.

To understand the multicurrency feature, you need to know about:

• ““Built-in” Vs. User Defined Currencies”
• “Active Vs. Inactive Currencies”
• “How Do You Set Currency Exchange Rates?”
• “What Happens in Transactions When You Change Exchange Rate?”

There are two categories of currencies supported by QuickBooks: QuickBooks’ own extensive list of built-in currencies and currencies added by the QuickBooks user, which are called user-defined currencies. (Currencies can be added either in the QuickBooks UI or with the SDK’s CurrencyAdd request.)

Both types of currencies show up in the UI Currency List or from the list obtained through the SDK’s CurrencyQuery request. In the Currency Query response, each currency is identified as built-in (the IsUserDefinedCurrency field is set to false) or as user-defined (the IsUserDefinedCurrency field is set to true).

Although the built-in currency list is extensive, you’ll notice that only a few show up in the various picklists in QuickBooks. That’s because only those few are active by default. You can change any of these to active (or from active to inactive) either in the UI or using the SDK’s CurrencyMod request.

When you create a currency using CurrencyAdd, the currency by default is active.

You can manually set the exchange rate for a currency itself by editing the currency in the UI, not through the SDK. However, there is a quasi-automatic rate update feature in QuickBooks that the user can invoke by clicking (from the main menu bar) List->Currency List->Activities->Download Latest Exchange Rates, which automatically fetches the currency rates for all built-in ACTIVE currencies over the Internet. This feature does not update user-defined currencies (these must be updated manually) and this feature is not available through the SDK.

The exchange rate setting for a currency is used by default when you add a transaction, either in UI or via SDK. However, these default exchange rates can be overridden by supplying a different exchange rate in the transaction, both in the QuickBooks UI and in the SDK through the ExchangeRate field.

When you change the exchange rate on transactions, the foreign value stays the same and the value in your home currency changes. Using the SDK, you can update the foreign price by modifying the transaction and specifying the latest exchange rate and then re-specify all of the transaction lines.

You cannot set multicurrency related preferences from the SDK. That has to be done in the UI.

By default company files are created with multicurrency turned off. To turn multicurrency on you have to use the QuickBooks UI with the company file open. From the main menu bar, Edit->Preferences->Multiple Currencies->Yes, I use more than once currency.

Once you turn multicurrency on for that company file, you won’t be able to turn it off ever again. There’s a prompt notifying you about this when you go to turn this on.

Next, you’ll need to specify the Home Currency, again you must do this in the UI, in the preferences as noted above. Once you set the Home Currency, you will not be able to change it later.

You can use the SDK to get the current company file settings for multicurrency by doing a PreferencesQuery using qbXML 8.0 or greater, you’ll get back a MultiCurrencyPreferences aggregate that contains the IsMultiCurrencyOn boolean and HomeCurrencyRef that indicates the home currency used with this company file.

QuickBooks keeps track of the line item amounts in both foreign and home currency, with the home currency amount calculated from the foreign amount using the exchange rate in effect for that transaction (foreign amount X exchange rate).

Amount balances for list objects (for example account, customer, and vendor) are in the currency associated with that account, customer, or vendor, and fluctuate based on the exchange rate.

All amounts in Reports have values expressed in home currency amounts, due to required accounting and reporting to government agencies.

Prior to QuickBooks 2009, developers were advised to explicitly supply the optional AP and AR account references instead of using the default Accounts Payable and Accounts Receivable. This advice was given to help developers avoid the scenario of mismatched AP and/or AR accounts when one transaction was linked to another.

With QuickBooks 2009 the ground has changed significantly due to the way QuickBooks does accounting for foreign currencies. QuickBooks automatically creates a new AP and/or AP account the first time a foreign transaction occurs in a given foreign currency. For example, for a new Invoice to a Japanese customer this AR account is created and used:

Accounts Receivable - JPY

So if you were to do an InvoiceAdd to that customer, you MUST either not specify the ARAccountRef (the SDK will automatically use the correct one) or you must refer to that new AR account explicitly–you cannot just use some other account.

For transactions that do not reference any other transaction, it is easier to not supply the AR or AP accountRef and let the defaults be used.

If your users are using QB 2009 and have multicurrency turned on, your application can be affected by multicurrency even if your application does not take advantage of the 8.0 features and issues only requests using qbXML spec 7.0 and older.

Here are the new behaviors that impact your app:

• Balances for customers and vendors, if they are set up with foreign currency, have the balance amount in that currency and that balance amount will fluctuate when exchange rates change.
• For transactions involving a foreign entity with foreign currency, transaction amounts are in that foreign currency. QuickBooks also tracks this in your home currency (say USD). However, that home currency is CALCULATED from the foreign amount using the current exchange rate, which can fluctuate.
• When a transaction occurs using a foreign currency for the first time, where there is an ARAccountRef and/or APAccountRef, QuickBooks will automatically create and use a foreign AR and/or AP account with the following FullName nomenclature:
  • Accounts Payable - Accounts Receivable - for example, if our transaction was in Japanese Yen, this is the account that would have to be referenced: Accounts Receivable - JPY Thus, if your application explicitly specifies a different AR or AP account it can fail when doing the transaction.

These are issues you need to be aware of.