Manage linked transactions

QuickBooks relates a sales or purchase transaction with its supporting transactions via the linked transaction mechanism. For example, a payment applied to a given invoice is considered a linked transaction to that invoice.

This tutorial shows how the QuickBooks Online API uses linked transactions and what information they supply to an Invoice object. It also explains what impact a linked transaction has on QuickBooks company accounts and how a customer’s payment maps to linked transactions in the accounting model.

To follow along, you’ll need a sandbox or another QuickBooks company populated with a chart of accounts, customers, invoices, and payments.

A linked transaction is realized in the QuickBooks Online API with the LinkedTxn element. The example below shows an Invoice object (Id=147) with a linked transaction to its corresponding Payment object (Id=190) via the LinkedTxn element. Some content has been omitted in order to showcase the linked transaction.

The linked transaction element provides the type and ID of the object. In order to get the complete details of the linked transaction, you must traverse the link to retrieve the object. For example, to retrieve the the linked transaction for the Invoice object above, where LinkedTxn.TxnType=Payment and LinkedTxn.TxnId=190, issue a request similar to the following:

1

https://quickbooks.api.intuit.com/v3/company/1386066315/payment/190

The table below lists all transactions that support linked transactions, along with the type of linked transactions.

The Invoice object returns linked transaction information in the Invoice.LinkedTxn array element. Two types of relationships are supported:

• Read-only links representing how it is paid, having a direct effect on the company’s accounts.
  • The ReimburseCharge, ChargeCredit, StatementCharge, or Payment objects can establish relationships to the Invoice object. Of these, the QuickBooks Online API supports the Payment relationship, only. See Notes about linked transactions in payment objects, below. The other relationships must be established and managed though the UI.
  • For these relationships, the Invoice.LinkedTxn elements are read-only on the Invoice side.
• Read-write links representing supporting information for the invoice. They don’t affect company accounts.
  • The Invoice object can create, update, and delete relationships to TimeActivity and Estimate objects.

A reimbursable charge corresponds to an expense incurred on behalf of a customer for which the amount needs to be invoiced. This relationship is established in the QuickBooks UI and is read-only through the API. Details for a reimbursable charge are sent in the Invoice object via the Line.SalesItemLineDetail as follows

• Line.SalesItemLineDetail.ItemRef: the id of the item object for the billable expense. If the expense does not correspond to an item in the company’s product and services list, this is set to 1.
• Line.SalesItemLineDetail.ItemAccountRef: the account associated with the reimbursable expense.
• Line.SalesItemLineDetail.MarkupInfo.MarkupAccountRef: the account associated with the markup expense.

In addition, ReimbursedCharge is returned in the Invoice.LinkedTxn element of the invoice object.

When an invoice is voided, either via the UI or QuickBooks Online API, the following operations are performed automatically by the underlying QuickBooks service.

• All amounts and quantities in the Invoice object are zeroed.
• Each Invoice.LinkedTxn link is cleared.
• Each Payment object is reset to its unapplied state:
  • The voided payment amount is added back to the Payment.UnappliedAmt attribute.
  • The Payment.Line.LinkedTxn elements related to the voided invoice are cleared.

See Invoice in the QuickBooks Online API Reference for specific details on how to void an invoice.

A Payment object represents funds collected from a customer, with a breakdown of how the funds are applied. The breakdown is a list of lines, with each item in the list represented by a Line.LinkedTxn element. The table below lists the possible type of linked transactions supported by Payment objects, with guidance on how to create them.

An expense object represents the purchases made from a vendor or customer. The breakdown is a list of lines, with each item in the list represented by a Line.LinkedTxn element. The table below lists the possible type of linked transactions supported by Expense objects, with guidance on how to create them.