Manage multiple currencies

In QuickBooks Online, currency refers to the money used for transactions. The multicurrency feature allows you to track transactions conducted in more than one currency.

By default, multicurrency is disabled in a QuickBooks company. It must be enabled in order to track transactions with currencies other than the company’s home currency. Multicurrency affects many accounts and balances in the company file, and therefore, cannot be disabled once it’s been enabled. ​An app can always choose not to use any of the multicurrency features even if it is enabled.

To follow along, you’ll need a sandbox or another QuickBooks company populated with a chart of accounts, customers, vendors, and invoices. The examples in this tutorial use the sandbox company.

• A currency can be assigned to customers, vendors/suppliers, price levels, bank accounts, credit card accounts, and accounts receivable/accounts payable accounts. Other account types, like income and expense accounts, always use the company’s home currency.
• Only one currency can be assigned to a given name list object or account.
• The multicurrency menu items are in the Company Settings menu under Manage Currency in the QuickBooks Online UI.
• Multicurrency is enabled from the QuickBooks Online UI, only. It cannot be enabled via the API.

In general, use the following attributes to track multicurrency transactions with the QuickBooks Online API. Consult the QuickBooks Online API Reference for details about multicurrency support on an individual entity basis.

The following image shows how these currency attributes in an Invoice transaction relate to the representation of the invoice in the UI.

Once set, the company’s home currency cannot be changed:

• For US QuickBooks Online editions, the home currency is set to USD, by default.
• For International QuickBooks Online editions, the user sets the home currency before enabling multicurrency.

View currency information, including the home currency setting, for the company on the Currencies list: select Currencies under Lists on the gear dropdown menu.

The Preferences entity read response contains the home currency setting.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
   "Preferences": {
        ...
      "TaxPrefs": {
        "UsingSalesTax": true
      },
      "CurrencyPrefs": {
         "MultiCurrencyEnabled": true,
         "HomeCurrency": {
           "value": "GBP"
         }
      },
         ...
}

Defines an external reference to a currency type.

1
2
3
4

"CurrencyRef": {
   "value": "currencyCode",
   ["name": "currencyName"]
}

where:

The examples below show an external reference to the the Canadian Dollar.

1
2
3
4
5
6
7
8

"Invoice": {
   ...
   "CurrencyRef": {
   "value": "CAD",
   "name": "Canadian Dollar"
   },
   ...
}

The currency center contains a list of active currencies and their corresponding exchange rates. When specifying currencies in customer objects, vendor objects, or transactions, all possible currencies are available from those listed in the currency code list. Those actually referenced are added to the active currency list automatically. Additionally, currencies can be added manually either through the UI or via the companycurrency API resource.

From here, you can view the home currency setting, view the list of active currencies and exchange rates used by your data, add rates to the list, and modify rates. Exchange rates are automatically updated via QuickBooks Online services. It is possible to override the current exchange rate setting from either the Currency Center UI or via the exchangerate API resource. In addition, you can override exchange rates for currencies used in transactions on the individual transaction object level via the object’s ExchangeRate parameter.

The focus of the following topics in this section discusses how to programmatically manage currencies using the companycurrency and exchangerate entities, in combination, from the QuickBooks Online API. Here you find information about:

• Retrieving an exchange rate
• Updating an exchange rate
• Retrieving the active currency list
• Adding a currency to the active currency list
• Removing a currency from the active currency list

Exchange rates are stored based on a combination of currency code and the rate’s effective date (the as-of date). As such, a request must specify both the currency code and the as-of date; today’s date is used for the as-of date if not explicitly defined in the request. For a given request, the company’s active currency list is queried followed by the global currency list. If neither list has the requested entry, an empty response is returned. For more information, see the exchangerate resource in the QuickBooks Online API Reference.

• <code> is the desired currency code. Required.
• <yyyy-mm-dd> is the desired effective date. If not specified, today’s date is used.

Content type: application/json

Example: To retrieve the exchange rate for EUR as of July 7, 2015, submit the following POST request:

https://QuickBooks.API.intuit.com/v3/company/<realmId>/exchangerate?sourcecurrencycode=EUR&asofdate=2015-07-07

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
   "ExchangeRate": {
      "SourceCurrencyCode": "EUR",
      "TargetCurrencyCode": "USD",
      "Rate": 2.5,
      "AsOfDate": "2015-07-07",
      "domain": "QBO",
      "sparse": false,
      "SyncToken": "1",
      "MetaData": {
         "LastUpdatedTime": "2015-07-08T09:24:02-07:00"
      }
   },
   "time": "2015-07-08T09:40:58.146-07:00"
}

The request code below updates the exchange rate between INR and USD to 7, effective July 8, 2015. In other words, effective July 8, 2015, 7 INR currency units equal 1 USD currency unit.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
   "SourceCurrencyCode": "INR",
   "TargetCurrencyCode": "USD",
   "Rate": 7,
   "AsOfDate": "2015-07-08",
   "SyncToken": "0",
   "MetaData": {
      "LastUpdatedTime": "2015-07-07T12:38:40-07:00"
   }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
   "ExchangeRate": {
      "SourceCurrencyCode": "INR",
      "TargetCurrencyCode": "USD",
      "Rate": 7,
      "AsOfDate": "2015-07-08",
      "domain": "QBO",
      "sparse": false,
      "SyncToken": "0",
      "MetaData": {
         "LastUpdatedTime": "2015-07-08T09:21:46-07:00"
      }
   },
   "time": "2015-07-08T09:21:46.310-07:00"
}

Use the query resource on the companycurrency endpoint to retrieve the active list of currencies.

1

select * from companycurrency

Note that you cannot query the companycurrency entity for the number of currency records with count(*).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

{
   "QueryResponse":
   {
      "CompanyCurrency":[
         {
            "Code":"JPY",
            "Name":"Japanese Yen",
            "Active":true,
            "domain":"QBO",
            "sparse":false,
            "Id":"5",
            "SyncToken":"0",
            "MetaData":
            {
               "CreateTime":"2015-06-19T09:20:44-07:00",
               "LastUpdatedTime":"2015-06-19T09:20:44-07:00"
            }
         },
         {
            "Code":"ANG",
            "Name":"Dutch Guilder",
            "Active":true,
            "domain":"QBO",
            "sparse":false,
            "Id":"4",
            "SyncToken":"0",
            "MetaData":
            {
               "CreateTime":"2015-06-12T14:16:38-07:00",
               "LastUpdatedTime":"2015-06-12T14:16:38-07:00"
            }
         },
         {
            "Code":"AUD",
            "Name":"Australian Dollar",
            "Active":true,
            "domain":"QBO",
            "sparse":false,
            "Id":"3",
            "SyncToken":"0",
            "MetaData":
            {
               "CreateTime":"2015-06-05T13:59:43-07:00",
               "LastUpdatedTime":"2015-06-05T13:59:43-07:00"
            }
         },
         {
            "Code":"EUR",
            "Name":"Euro",
            "Active":true,
            "domain":"QBO",
            "sparse":false,
            "Id":"2",
            "SyncToken":"0",
            "MetaData":
            {
               "CreateTime":"2015-06-05T13:59:42-07:00",
               "LastUpdatedTime":"2015-06-05T13:59:42-07:00"
            }
         },
         {
            "Code":"CAD",
            "Name":"Canadian Dollar",
            "Active":true,
            "domain":"QBO",
            "sparse":false,
            "Id":"1",
            "SyncToken":"0",
            "MetaData":
            {
               "CreateTime":"2015-06-05T13:59:42-07:00",
               "LastUpdatedTime":"2015-06-05T13:59:42-07:00"
            }
         }
      ],
      "startPosition":1,
      "maxResults":5,
      "totalCount":5
   },
   "time":"2015-07-06T13:29:01.560-07:00"
}

Use the companycurrency resource to add a currency.

1
2
3

{
   "Code":"GBP"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
   "CompanyCurrency": {
      "Code": "GBP",
      "Name": "British Pound Sterling",
      "Active": true,
      "domain": "QBO",
      "sparse": false,
      "Id": "7",
      "SyncToken": "0",
      "MetaData": {
         "CreateTime": "2015-07-06T13:34:48-07:00",
         "LastUpdatedTime": "2015-07-06T13:34:48-07:00"
      }
   },
   "time": "2015-07-06T13:34:48.569-07:00"
}

Removing a currency from the active list is achieved by setting theActiveattribute tofalsein an entity update request; thus, making it inactive. In this type of delete, the record is not permanently deleted, but is hidden for display purposes from the currency center and active currency list. References to inactive objects are left intact. Reactivating an inactive companycurrency object creates a new object, rather than updating the older onewith Active=true.

The example below shows an update request with Active=false.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
   "Code": "GBP",
   "Name": "British Pound Sterling",
   "Active": false,
   "domain": "QBO",
   "sparse": false,
   "Id": "7",
   "SyncToken": "0",
   "MetaData": {
      "CreateTime": "2015-07-06T13:34:48-07:00",
      "LastUpdatedTime": "2015-07-06T13:34:48-07:00"
   }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
   "CompanyCurrency": {
      "Code": "GBP",
      "Name": "British Pound Sterling",
      "Active": false,
      "domain": "QBO",
      "sparse": false,
      "Id": "7",
      "SyncToken": "0",
      "MetaData": {
         "CreateTime": "2015-07-06T13:34:48-07:00",
         "LastUpdatedTime": "2015-07-06T13:34:48-07:00"
      }
   },
   "time": "2015-07-06T13:34:48.569-07:00"
}

The primary key for these tables is a combination of the currency code and as-of date. When a request is made, the company exchange rate table is searched first. If not found, the global exchange rates table is searched. If neither table has the entry, an empty response is returned.

Define the currency in which you use to pay supplier at the time you create the supplier. Once configured, it cannot be changed.

Define the currency with the Rest API Vendor create request, using the CurrencyRef attribute. The vendor below is defined with GBP as his currency.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
"Vendor"
   {
      "BillAddr": {
         "Id": "24",
         "Line1": "Staines",
         "City": "Middlesex",
         "PostalCode": "TW18 3JY",
         "Lat": "51.4314384",
         "Long": "-0.4989863"
      },
      "CurrencyRef": {
         "value": "GBP",
         "name": "British Pound Sterling"
      },
       ...
      "GivenName": "Andrew",
      "FamilyName": "Haberbosch",
      "CompanyName": "Andrew Haberbosch",
      "DisplayName": "Andrew Haberbosch",
      "PrintOnCheckName": "Andrew Haberbosch",
      "Active": true
   }
}

Define the currency in which customers pay you. Once configured, it cannot be changed.

Define the currency with the Rest API Customer create request, using the CurrencyRef attribute.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
   "Customer": [
      {
        "Taxable": false,
        "BillAddr": {
          "Id": "69",
          "Line1": "Nottingham",
          "City": "Nottingham",
          "Country": "United Kingdom",
          "PostalCode": "NG2 5FA"
        },
            ...
        "CurrencyRef": {
          "value": "USD",
          "name": "United States Dollar"
        },
            ...
        "GivenName": "Kristy",
        "FamilyName": "Abercrombie",

      }
 }

Assign the currency, on an individual account basis, that is used with funds in your accounts. Most accounts can be assigned a currency; accounts like income and expense accounts always use the company’s home currency. Once configured, the currency for an account cannot be changed.

Define the currency with the Rest API Account create request, using the CurrencyRef attribute.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "Name": "AR-US",
  "FullyQualifiedName": "AR-US",
  "Active": true,
  "Classification": "Asset",
  "AccountType": "Accounts Receivable",
  "AccountSubType": "AccountsReceivable",
  "CurrentBalance": 916.5,
  "CurrentBalanceWithSubAccounts": 916.5,
  "CurrencyRef": {
    "value": "USD",
    "name": "United States Dollar"
  },
...
}

View the ExchangeRate reference here and CompanyCurrency here.

Here is the list of ISO 4127 currency codes supported by the QuickBooks Online API.