Home Portal

Skip to end of metadata
Go to start of metadata
Integration with QuickBooks Online, a web-based version of a popular accounting software developed by Intuit.

There is a separate integration engine which supports desktop version of QuickBooks.

Table of Contents

Supported QuickBooks Online Versions and Changelog

The integration works with QuickBooks Online. For detailed information about supported versions and a list of introduced changes, see: QuickBooks and QuickBooks Online Integration Compatibility.

General Description

XTRF and QuickBooks Online integration can be divided into three groups of processes:

  1. Partner creation and management;
  2. Invoice creation and management;
  3. Payment creation and management.

Partners (i.e. Clients or Vendors) get synchronized from XTRF to QuickBooks Online whenever a new partner is created or modified in XTRF. The partner data gets synchronized only in this direction - no changes made in QuickBooks Online get reflected in XTRF.

It is also assumed that XTRF is the only source of origin for invoices. The difference, compared to partners synchronization, is that the integration only creates new invoices in QuickBooks Online, but does not modify them when they get modified in XTRF.

In case of payments, the integration checks for new payments that appear in QuickBooks Online. If there are some new payments, the integration queries QuickBooks for all invoices unpaid in XTRF to check which of them have been paid. After querying all invoices, the integration creates respective payments in XTRF and marks appropriate XTRF invoices as paid or partially paid.

For more details about synchronizing data, see Synchronization section below.


See: QuickBooks Online Integration Pre-configuration .


The following list summarizes the synchronization mechanizm of the integration with QuickBooks Online.


The integration synchronizes the following data:

  • from XTRF to QuickBooks Online:
    • Client information
    • Vendor information
    • Client Invoices
    • Vendor Invoices
  • from QuickBooks Online to XTRF:
    • Client Payments
    • Vendor Payments

The integration can be configured to synchronize:

  • both the Clients and Vendors data (including their invoices and payments data)
  • Clients data only
  • Vendors data only

During the initial synchronization, the integration checks:

  • edition of QuickBooks Online - US vs. International
  • currencies and whether QuickBooks Online works in single-currency or multi-currency mode (the latter is available only in Interational Edition).
  • default QuickBooks account
  • default invoice item names
  • existing Payment conditions in QuickBooks

 Clients and Vendors (together refered to as partners) are synchronized only from XTRF to QuickBooks Online.

  • When new partner is created in XTRF, or a partner not synchronized before gets modified, the integration checks if a partner with given name exists in QuickBooks Online.
    • if they do not exist, they get created and their QuickBooks identifier gets stored in XTRF as a synch key 
    • if they have already existed, they get remembered in XTRF by their QuickBooks identifier (synchronization key). Additionally, the integration ensures that all partner data is up-to-date with the respective data in XTRF (the data in QuickBooks Online gets overwritten).
    • if they have already existed and had their synchronization key, but cannot be matched by that key with a Partner in QuickBooks, then a recovery mechanism is run - XTRF deletes the synchronization key and tries to match the Partner by name. If found, a new synchronization key is stored and the modifications from XTRF are transferred to QuickBooks. Otherwise, the synchronization creates a new Partner in QuickBooks according to XTRF data and also stores a new synchronization key.
  • When partner data is modified in XTRF, the corresponding data in QuickBooks Online gets synchronized accordingly. All differences in QuickBooks Online get overwritten by the latest data from XTRF.
  • Once a partner is issued their first invoice in XTRF, their data is also automatically transferred to QuickBooks Online and updated.
  • Inactive Clients and Vendors are not synchronized. If a Client or Vendor has already been synchronized and has later been deactivated in XTRF, they get deactivated in QuickBooks Online as well.
  • In XTRF a Client or Vendor can have several Price Profiles in different currency. In QuickBooks Online they can have only one currency assigned. Thus, during the synchronization, the currency from the partner's default Price Profile in XTRF gets set in QuickBooks Online.

Please note that XTRF is considered by the integration as a source of partner data. No changes made to partner profiles in QuickBooks Online will be reflected in XTRF. Moreover, they will get overwritten during the next synchronization by the XTRF data.


Invoices are synchronized to QuickBooks Online depending on their status. The invoice status required for the synchronization to take place can be configured, and can be different for Client and Vendor invoices.

  • The synchronization takes place for new invoices, i.e. invoices without synchronization key, modified later than the value of the field 'Synchronize items newer than' in the configuration menu.
  • The integration ensures that all data required for the synchronization is provided. This means in particular that:
    • owning partner's synchronization key must exist in XTRF (otherwise, it is added or partners recovery mechanism is run);
    • for vendor invoices all Clients synchronization keys related to invoice item must exist in XTRF (otherwise, the integration reports an error);
    • payment condition must exist in QuickBooks Online (otherwise, it is added);
    • all invoice item names generated from expressions must exist (otherwise, they are added)
  • When the XTRF invoice is set to the appropriate status, the integration creates an invoice in QuickBooks Online based on XTRF data, and stores QuickBooks ID (synch key).
  • The integration synchronizes invoice Net Total values (VAT and gross values are not supported).
  • Zero-value invoices do not get synchronized. Invoices without numbers in "Invoice No." field do not get synchronized either.
  • The integration does not synchronize Pro Forma Invoices.
  • If the value of the items in XTRF invoice does not equal the total invoice value, then in QuickBooks Online an additional item is created. For example, in XTRF: item1 = 100 USD, item2 = 200 USD, total = 400 USD. Then, in QuickBooks there will an additional item3 = 100 USD.

In general, the integration assumes that invoice always originates from XTRF. However, from version 6.6, for XTRF invoices with no synchronization key, the integration queries the invoices in QuickBooks Online by invoice number and verifies if the owning partner is the same as in XTRF. If a matching invoice is found in QuickBooks, the synchronization stores a synchronization key for it. Otherwise, a new invoice gets created in QuickBooks Online.

The integration queries does not modify invoices in QuickBooks Online when they are modified in XTRF. Also, once sent, the invoice would not change in XTRF. If an invoice needs to be changed, the user has to delete the invoice in QuickBooks Online and its synch key in XTRF first. Then, after entering the changes in XTRF, the invoice has to be resynchronized.


Payments are synchronized only from QuickBooks Online to XTRF.

  • Synchronization checks for new payments in QuickBooks Online.
  • If there are new payments, the integration queries QuickBooks Online for all invoices unpaid in XTRF to check which of them have been paid:
    • the integration queries QuickBooks invoice by synchronization key, gets information about invoice payments, and matches it with Payment information received before
    • if XTRF is unable to query QuickBooks invoice by ID (Response: no such invoice), then invoice recovery is run - XTRF tries to find given invoice by its invoice number. If found, new invoice's synch key is stored. Otherwise, invoice is recreated in QuickBooks Online.

      Invoice recovery is run only when new payments appear. It is required for payments synchronization. Therefore, the same data may be used for both payments synch and recovery, if needed.
  • After querying all invoices, the integration creates respective payments in XTRF and marks appropriate XTRF invoices as paid or partially paid.
 QuickBooks can work in single-currency of multi-currency mode. In case of single-currency mode, the values in different currencies from XTRF are calculated to QuickBooks currency according to the exchange rate set up in XTRF. (See also: Currency in QuickBooks Online API documentation.)
For additional information, see also: Field Mapping between QuickBooks Online and XTRF.

Company Files Management

QuickBooks Online integration supports only one company file. The synchronization can be performed with only one QuickBooks Online instance.

QuickBooks Online Documentation

See: https://help.quickbooks.intuit.com/

  • No labels