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.

    Note

    Multicurrency is not available with QuickBooks Simple Start.

    Using multicurrency with the QuickBooks Online API

    • 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.

    Attribute

    Description

    ExchangeRate

    Currency exchange rate. Exchange rates are always recorded as the number of home currency units it takes to equal one foreign currency unit. 

    CurrencyRefThe reference to the currency in which all amounts on the associated transaction are expressed. 
    HomeTotalAmtAvailable in some transaction entities. A convenience field to show the total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
    TotalAmtThe total amount of the transaction in terms of the currency defined for the transaction.

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

    AuCadCurrencyInvoice.jpg

    Home currency

    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. 

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

    Currency references

    Defines an external reference to a currency type.  

    Synopsis

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

    where:

    currencyName

    An identifying name for the currency as defined by data services.  This parameter is returned in GET responses; this name cannot be changed and is ignored in POST requests. 

    currencyCode

    A three letter string representing the ISO 4217 code for the currency.

    Examples

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

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

    Currency center and exchange rates

    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.   

    Currencies.jpg

    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:

    Managing exchange rates

    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.

    Retrieving an exchange rate

    Request

    Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com/v3
    Production Base URL: https://quickbooks.api.intuit.com/v3
    Operation:      GET /company/<realmID>/exchangerate?sourcecurrencycode=code[&asofdate=yyyy-mm-dd]
                            where:

    • 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

    Response
    Click here for sample response.
    {
        "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"
    }
    

    Updating an exchange rate

    Request

    Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com/v3
    Production Base URL: https://quickbooks.api.intuit.com/v3
    Operation:      POST /company/<realmID>/exchangerate
    Content type:application/json

    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.

    Click here for sample request.
    {
        "SourceCurrencyCode": "INR",
        "TargetCurrencyCode": "USD",
        "Rate": 7,
        "AsOfDate": "2015-07-08",
        "SyncToken": "0",
        "MetaData": {
            "LastUpdatedTime": "2015-07-07T12:38:40-07:00"
        }
    }
    
    Response
    Click here for sample response.
    {
        "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"
    }
    

    Managing the active currency list

    Retrieving the active currency list

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

    Request

    Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com/v3
    Production Base URL: https://quickbooks.api.intuit.com/v3
    Operation:      POST /company/<realmID>/query=select * from companycurrency
    Content type:application/text

    Click here for sample request.
    select * from companycurrency

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

    Response
    Click here for sample response.
    {
        "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"
    }
    

    Adding a currency to the active currency list

    Use the companycurrency resource to add a currency.

    Request

    Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com/v3
    Production Base URL: https://quickbooks.api.intuit.com/v3
    Operation:      POST /company/<realmID>/companycurrency
    Content type:application/json

    Click here for sample request.
    {
      "Code":"GBP"
    }
    
    Response
    Click here for sample response.
    {
        "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 currency list

    Removing a currency from the active list is achieved by setting the Active attribute to false in 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 one with Active=true

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

    Request

    Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com/v3
    Production Base URL: https://quickbooks.api.intuit.com/v3
    Operation:      POST /company/<realmID>/salesreceipt
    Content type:application/json

    Click here for sample request.
    {
            "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"
            }
        }
    
    Response
    Click here for sample response.
    {
        "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.

    Vendor/Supplier currency configuration

    Configure with the UI

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

    Configure via data services

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

       {
        "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
          }
        }
    

    Customer currency configuration

    Configure with the UI

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

    Configure via data services

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

    {
        "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",
    
            }
     }
    
    

    Account currency configuration

    Configure with the UI

    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.

    AccountCreateMC.png

    Configure via data services

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

          {
            "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"
            },
          ...
          }
    
    

    Currency Codes

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

    Click here to see codes.
    CodeCurrency
    AEDUAE Dirham
    AFNAfghani
    ALLLek
    AMDArmenian Dram
    ANGNetherlands Antillean Guilder
    AOAKwanza
    ARSArgentine Peso
    AUDAustralian Dollar
    AWGAruban Florin
    AZNAzerbaijanian Manat
    BAMConvertible Mark
    BBDBarbados Dollar
    BDTTaka
    BGNBulgarian Lev
    BHDBahraini Dinar
    BIFBurundi Franc
    BMDBermudian Dollar
    BNDBrunei Dollar
    BOBBoliviano
    BRLBrazilian Real
    BSDBahamian Dollar
    BTCBitcoin
    BTNNgultrum
    BWPPula
    BYRBelarussian Ruble
    BZDBelize Dollar
    CADCanadian Dollar
    CDFCongolese Franc
    CHFSwiss Franc
    CLPChilean Peso
    CNYYuan Renminbi
    COPColombian Peso
    CRCCosta Rican Colon
    CUPCuban Peso
    CVECabo Verde Escudo
    CZKCzech Koruna
    DJFDjibouti Franc
    DKKDanish Krone
    DOPDominican Peso
    DZDAlgerian Dinar
    EGPEgyptian Pound
    ERNNakfa
    ETBEthiopian Birr
    EUREuro
    FJDFiji Dollar
    FKPFalkland Islands Pound
    GBPPound Sterling
    GELLari
    GHSGhana Cedi
    GIPGibraltar Pound
    GMDDalasi
    GNFGuinea Franc
    GTQQuetzal
    GYDGuyana Dollar
    HKDHong Kong Dollar
    HNLLempira
    HRKKuna
    HTGGourde
    HUFForint
    IDRRupiah
    ILSNew Israeli Sheqel
    INRIndian Rupee
    IQDIraqi Dinar
    IRRIranian Rial
    ISKIceland Krona
    JMDJamaican Dollar
    JODJordanian Dinar
    JPYYen
    KESKenyan Shilling
    KHRRiel
    KMFComoro Franc
    KPWNorth Korean Won
    KRWWon
    KWDKuwaiti Dinar
    KYDCayman Islands Dollar
    KZTTenge
    LAKKip
    LBPLebanese Pound
    LKRSri Lanka Rupee
    LRDLiberian Dollar
    LSLLoti
    LTLLithuanian Litas
    LVLLatvian Lats
    LYDLibyan Dinar
    MADMoroccan Dirham
    MDLMoldovan Leu
    MGAMalagasy Ariary
    MKDDenar
    MMKKyat
    MNTTugrik
    MOPPataca
    MROOuguiya
    MURMauritius Rupee
    MVRRufiyaa
    MWKKwacha
    MXNMexican Peso
    MYRMalaysian Ringgit
    MZNMozambique Metical
    NADNamibia Dollar
    NGNNaira
    NIOCordoba Oro
    NOKNorwegian Krone
    NPRNepalese Rupee
    NZDNew Zealand Dollar
    OMRRial Omani
    PABBalboa
    PENNuevo Sol
    PGKKina
    PHPPhilippine Peso
    PKRPakistan Rupee
    PLNZloty
    PYGGuarani
    QARQatari Rial
    RONRomanian Leu
    RSDSerbian Dinar
    RUBRussian Ruble
    RWFRwanda Franc
    SARSaudi Riyal
    SBDSolomon Islands Dollar
    SCRSeychelles Rupee
    SDGSudanese Pound
    SEKSwedish Krona
    SGDSingapore Dollar
    SHPSaint Helena Pound
    SLLLeone
    SOSSomali Shilling
    STDDobra
    SVCEl Salvador Colon
    SYPSyrian Pound
    SZLLilangeni
    THBBaht
    TJSSomoni
    TMTTurkmenistan New Manat
    TNDTunisian Dinar
    TOPPa’anga
    TRYTurkish Lira
    TTDTrinidad and Tobago Dollar
    TWDNew Taiwan Dollar
    TZSTanzanian Shilling
    UAHUkranian Hryvnia
    UGXUganda Shilling
    USDUS Dollar
    UYUPeso Uruguayo
    UZSUzbekistan Sum
    VEFBolivar
    VNDVietnam Dong
    VUVVatu
    WSTTala
    XAFCFA Franc BEAC
    XCDEast Caribbean Dollar
    XOFCFA Franc BCEAO
    XPFCFP Franc
    YERYemeni Rial
    ZARRand
    ZMWZambian Kwacha

    Learn more

    View the ExchangeRate reference here and CompanyCurrency here.


    Did you find this page helpful?
    Your feedback helps us make our docs better. Please let us know if this page helped you, or if it needs improvement.

     Got Questions? Get Answers in our developer forums.