Linking item reciept and bill to purchase order, invoice to sales order

In the QuickBooks UI, a user can receive items against purchase orders, and the purchase orders will be automatically updated. The same thing happens when the user enters bills against purchase orders. Similarly, a user can invoice against existing sales orders, and the sales orders are automatically updated.

In the SDK, the request messages for adding item receipts, bills, and invoices contain elements for identifying the originating purchase order or sales order. Supplying information that identifies the purchase order or sales order achieves the same results that adding an item receipt, bill, or sales order through the UI does–the purchase order or sales order is updated.

This page reviews how users enter item receipts, bills, and invoices in the UI and then shows how to construct ItemReceiptAddRq, BillAddRq, and InvoiceAddRq messages that achieve the same results–the matching purchase order or sales order is updated appropriately.

Note

Note

In the SDK, this functionality is only available with add requests–not in modify requests.

Linking item receipts and bills to purchase orders

The message elements for identifying the originating purchase orders are LinkToTxn and LinkToTxnId, so the process is referred to as linking item receipts or bills to purchase orders, and once the request has been sent, the transactions are referred to a linked transactions. Before looking at how to build SDK requests that link, a brief review of how the links are built in the QuickBooks UI.

Linking in the QuickBooks UI

The following steps briefly review the process for linking transactions in the QuickBooks UI.

In the QuickBooks UI, when a user creates an item receipt or a bill, the user also selects a vendor. If there any open purchase orders for that vendor, QuickBooks presents the user with a selection list of purchase orders.
After the user links the item receipt or bill to a purchase order, QuickBooks fills the item receipt or bill with data from the selected purchase order, so that the item receipt or bill contains every receivable line item from the purchase order:

Notice that the data pulled from the purchase order includes the purchase order number–which is circled in the lower right of the figure. This shows which line items belong to which purchase order, which is useful when the item receipt or bill covers items from multiple purchase orders and the user links the item receipt or bill to multiple purchase orders.
The user’s next action depends on whether the items received complete the purchase order.
1. If the received items complete the originating purchase order, the user indicates this by clicking the Save and Close” button. If the user does this and subsequently displays the PurchaseOrder it will indicate that all its items were received, as shown below:
2. If the user received only some of the items in the purchase order, the user modifies the quantity field for any line item that was not fully received. See the circled area in the following figure:
  
  The PurchaseOrder in this case would not display the “Received in Full” stamp, but would show received and unreceived items with the number received indicated. The fully received items are marked as closed “Clsd.” See the circled area below.

Linking with the SDK

The results that were achieved in the preceding UI scenario are achieved in the SDK by supplying transaction IDs in ItemReceiptAddRq or BillAddRq messages to indicate which purchase orders should be linked:

To link an item receipt or bill to one or more entire purchase order (to indicate that all of the line items in the purchase order have been received or billed and close out the purchase order, equivalent to option 3a above), use the LinkToTxnID element to identify the purchase order. This will add all of the line items in the specified purchase order to the item reciept or bill. Purchase orders linked in this way to an item receipt will be marked as received in full and will be closed as a result of the request. The first of the following figures shows an excerpt from the API Reference page for the BillAdd request with the LinkToTxnID element circled.
To link an item receipt or bill to a subset of the line items in one or more purchase orders (equivalent to option 3b above), use the LinkToTxn aggregate inside the ItemLineAdd aggregate.Typically, if all the items don’t arrive at the same time, separate item receipts are issued as the items are received. Purchase orders linked to item receipts in this way will be closed only when all of the items have been received. The second following figure shows an excerpt from the API Reference page for the BillAdd request with the LinkToTxn aggregate circled.

Note

Note

Purchase Orders are automatically closed and marked as fully received when the item receipts linked to them fully receive the purchase order line items. However, if you want to close a Purchase Order or close out line items in a Purchase Order without receiving the items, you can perform a PurchaseOrderMod and manually close individual line items or the Purchase Order itself.

Excerpt from the API Reference page for the BillAdd request with the LinkToTxn aggregate circled:

Request message for a bill that operates on all of the purchase order lines

The following sample BillAddRq message shows a bill that is linked to two different purchase orders using LinkToTxnID. The resulting bill will contain all of the line items from both specified purchase orders.

<?qbxml version="4.0"?>
<QBXML>
    <QBXMLMsgsRq onError="stopOnError">
        <BillAddRq requestID="2">
            <BillAdd>
                <VendorRef>
                    <FullName>Daigle Lighting</FullName>
                </Vendorref>
                <APAccountRef>
                    <FullName>Accounts Payable</FullName>
                </APAccountRef>
                <TxnDate>2004-10-28</TxnDate>
                <DueDate>2004-11-28</DueDate>
                <TermsRef>
                    <FullName>Net 30</FullName>
                </Termsref>
                <LinkToTxnID>25D6-1071508328</LinkToTxnID>
                <LinkToTxnID>53C4-1197730858</LinkToTxnID>
            </BillAdd>
        </BillAddRq>
    </QBXMLMsgsRq>
</QBXML>

In the above sample request, notice the following:

The use of the VendorRef element–the vendor specified in the request must match the vendor in all of the purchase orders identifed in the message. A message can only specify one vendor.
The use of the APAccountRef element–while not required, use of this element is highly recommended. If your request doesn’t include a value, QuickBooks will use the default AP account, which may cause problems if the company file has AP accounts other than the default AP account. If the company has more than one AP account and the APAccountRef is omitted from the bill, it opens the possibility of the bill payment specifying a different AP account.
The use of two LinkToTxnID elements to identify the two purchase orders that are to be linked and closed. The request will fail if the specified purchase orders have already been closed.

The result of this sample request is that every receivable line item in the two linked purchase orders are considered received and closed, and the two purchase orders are entirely closed.

Request message for a bill that operates on selected purchase order line es

The following sample BillAddRq message shows a bill that is linked to two line items from one purchase order. The resulting bill will contain only the two specified line items.

<?qbxml version="4.0"?>
<QBXML>
    <QBXMLMsgsRq onError="stopOnError">
        <BillAddRq requestID="2">
            <BillAdd>
                <VendorRef>
                    <FullName>Daigle Lighting</FullName>
                </VendorRef>
                <APAccountRef>
                    <FullName>Accounts Payable</FullName>
                </APAccountref>
                <TxnDate>2004-10-28</TxnDate>
                <DueDate>2004-11-28</DueDate>
                <TermsRef>
                    <FullName>Net 30</FullName>
                </TermsRef>
                <ItemLineAdd>
                    <LinkToTxn>
                        <TxnID>53DD-1197743928</TxnID>
                        <TxnLineID>53DF-1197743928</TxnLineID>
                     </LinkToTxn>
                </ItemLineAdd>
                <ItemLineAdd>
                    <LinkToTxn>
                        <TxnID>53DD-1197743928</TxnID>
                        <TxnLineID>53E0-1197743928</TxnLineID>
                    <LinkToTxn>
                </ItemLineAdd>
            </BillAdd>
        </BillAddRq>
    </QBXMLMsgsrq>
</QBXML>

Request message for a bill that operates on selected lines from multiple purchase orders

The following sample BillAddRq message shows a bill that is linked to selected line items from multiple purchase orders. The resulting bill will contain only the selected line items.

<?qbxml version="4.0"?>
<QBXML>
    <QBXMLMsgsRq onError="stopOnError">
        <BillAddRq requestID="2">
            <BillAdd>
                <VendorRef>
                    <FullName>Daigle Lighting</FullName>
                </VendoRref>
                <APAccountRef>
                    <FullName>Accounts Payable</FullName>
                </APAccountRef>
                <TxnDate>2004-10-28</TxnDate>
                <DueDate>2004-11-28</DueDate>
                <LinkToTxnID>25D6-1071508328</LinkToTxnID>
                <LinkToTxnID>53C4-1197730858</LinkToTxnID>
                <TermsRef>
                    <FullName>Net 30</FullName>
                </TermsRef>
                <ItemLineAdd>
                    <LinkToTxn>
                        <TxnID>53DD-1197743928</TxnID>
                        <TxnLineId>53DF-1197743928</TxnLineId>
                    </LinkToTxn>
                </ItemLineAdd>
                <ItemLineAdd>
                    <LinkToTxn>
                        <TxnID>58DD-1197743928</TxnID>
                        <TxnLineID>53E0-1197743928</TxnLineID>
                    </LinkToTxn>
                </ItemLineadd>
            </BillAdd>
        </BillAddRq>
    </QBXMLMsgsRq>
</QBXML>

In the above sample request, notice the following:

A request can combine TxnID and TxnLineID liniks.
A request can link an item receipt or bill to multiple purchase orders, as long as the purchase orders are from the same vendor, which is specified in the VendorRef.

Rules for linking item receipts and bills to purchase orders

The following rules are enforced during runtime, and are listed here to help you avoid runtime errors, some of which may not be obvious to track down and fix.

Rule 1: Don’t use the same TxnID in a LinkToTxnID element and a LinkToTxn aggregate in the same item receipt or bill.
Rule 2: If you link to specific line items with the LinkToTxn aggregate, you must maintain the order of lines between the item receipt or bill and the purchase order. For example, you may not list a LinkToTxn aggregate for purchase order line #2 and then list a LinkToTxn aggregate for purchase order line #1. The LinkToTxn aggregate specifying purchase order line #1 must precede the LinkToTxn aggregate specifying purchase order line #2, and so on.
Rule 3: If you use LinkToTxn aggregates, you cannot mix lines from different purchase orders in the ItemReceipt or Bill. That is, you cannot specify line #1 of purchase order A, then line #1 of purchase order B followed by line #2 of purchase order A, and so on. You must list all of the desired lines of purchase order A, in order, before speciflying any lines of purchase order B.
Rule 4: If a purchase order contains a group line item, you must link to the individual lines within the group, not to the group itself. A group item is essentially a UI convenience and is not linkable.
Rule 5: When linking an item receipt or bill to a purchase order, the vendors (in the VendorRef aggregates) for each of these must match.
Rule 6: You may only link to receivable purchase order lines. That is, for that purchase order line, the ReceivedQuantity element must exist, it cannot be marked manually closed, and the Quantity must be greater than the ReceivedQuantity.
Rule 7: You cannot specify both an ItemRef and a LinkToTxn aggregate within the same line item. You will get a conflict error.

Converting item receipts to bills

The QuickBooks UI makes it look like item receipts can be linked to bills by clicking the Receive Bill icon in the vendor navigator. However, the UI has not actually linked the item receipt to the bill, it has converted the item receipt to a bill. If you query for the item receipt, it will no longer be there, and the purchase order will show only the link to the bill.

Notice that although the UI actually converts this transaction, that same functionality does not exist in the SDK. However, you can achieve the same end result by deleting the ItemReceipt using the TxnDel request and using BillAdd to link a bill to the PurchaseOrder instead of an ItemReceipt.

Split option for bills and item receipts in QuickBooks Enterprise

ItemReceipt and Bill transaction split is a feature which allows an ItemReceipt and a Bill to be two transactions on their own instead of one transaction that shares the ItemReceipt and Bill states. The ItemReceipt/Bill split feature was created to solve inventory requirements from our users that the current existing design of one transaction did not solve. For example, a user writes up an ItemReceipt on 1/1/2011 for receiving some inventories and then on 2/1/2011, a Bill is received. In the one-transaction design the Bill on 2/1/ 2011 will replace the ItemReceipt on 1/1/2011. This will create a problem of not enough quantity on hand for building assemblies that depend on receiving inventories on 1/1/2011. This feature will only be available to Enterprise users and is controlled by aQuickBooks preference that allows users to continue with the one-transaction design or completely switch to the new two-transaction split design.

ItemReceipt and Bill can be brought up separately in the UI and edited simultaneously by our users. They no longer share the same UI with a check box to identify as an ItemReceipt or Bill.
Two new link types will be introduced. One new link type is to allow linking from a Purchase Order to a Bill, since the Bill is split from the ItemReceipt. Another new link type is to allow linking from ItemReceipt to Bill or reverse since ItemReceipt and Bill are separate transactions.
Purchase Order targets will contain two new fields to hold information about the Bills they link to.
ItemReceipt cost will no longer be allowed to be edited by users and they will contain the average costing of the Bills in the order.
A new Inventory Offset account is introduced to wash the monies posted between ItemReceipts and Bills.
ItemReceipts will post against Inventory Offset (src target) and Inventory Asset/ income/expense (dist targets).
Bills will post against Account Payable (src targets) and Inventory Offset (dist targets).
Item history will only pick up ItemReceipt targets with Inventory Offset account for calculating quantity and on hand and average costing.

Linking invoices to sales orders

The procedures for linking invoices to sales orders, both in the UI and with the SDK, are very similar to those for linking item receipt and bills to purchase orders. As is the case with those other types of transaction linking, it helps to first take a look at how this feature works within the QuickBooks UI.

Note

Note

Since a sales order is a non-posting transaction, QuickBooks business logic doesn’t require the sales tax information at the time when a sales order is added. However, the business logic does require the sales tax item for an invoice. So, if a sales order doesn’t have a SalesTaxItem set for it, you need to add it with a modify request before you create an invoice using that sales order.

Linking in the QuickBooks UI

In the QuickBooks UI, when a user creates an invoice, the user also selects a customer. If there any outstanding sales orders for that customer, QuickBooks presents the user with a selection list of sales orders.
If the user selects one or more of the sales orders, the user is prompted for the type of linking, as shown below. The choices are import all of the sales order lines, or select some of them.
1. If the user chooses “Create invoice for all of the sales order(s)” then for each sales order selected in the list, all of the line items will be added to the invoice as shown in the next figure:
  
  In this scenario, all of the sales order lines and quantities are imported: notice in the circled area that the source sales order for each line is listed, and the ordered quantities and the invoiced quantities are the same. The user can change the invoiced quantities.
2. If, instead of choosing to invoice against entire sales orders, the user chooses “Create invoice for selected items”, an invoice quantities form is posted to allow the user to change quantities before the sales order lines are pulled into the invoice form as shown below:
  
  The user simply changes the quantities as desired, or enters a value of 0 if the customer isn’t to be invoiced for a particular item. (By default, QuickBooks doesn’t print invoice items with 0 quantities, but note that the user can change this.) When the user is done, the populated invoice form is shown.

Automatic selection of invoice template

In the UI, if the user invoices against more than one sales order, the default invoice template changes to the multiple sales order template. This same behavior is reflected in the Desktop SDK. That is, if you don’t specify a template in the TemplateRef and you link to more than one sales order, the default invoice template that will be used is the multiple sales order template.

Linking with the SDK

The results that were achieved in the preceding UI scenario are achieved in the SDK by supplying transaction IDs in InvoiceAddRq messages to indicate which invoices should be linked:

To link an invoice to one or more entire sales orders (equivalent to option 2a above), use the LinkToTxnID element to identify the sales order. This will add all of the line items in the specified sales order to the invoice. The sales orders linked in this way to an invoice will be marked as fully invoiced and closed. The first of the following figures shows an excerpt from the API Reference page for the InvoiceAdd request with the LinkToTxnID element circled.
To link an invoice to a subset of the line items in one or more sales orders (equivalent to option 2b above), use the LinkToTxn aggregate inside the ItemLineAdd aggregate. Sales orders linked in this way to invoices will be closed only after all of the items are invoiced. The second following figure shows an excerpt from the API Reference page for the InvoiceAdd request with the LinkToTxn aggregate circled.

Note

Note

If you link your invoice to a sales order that contains a customer address, the result is that the sales order’s address will be pulled in and used, even if you specify a different BillAddress and/or ShipAddress in the InvoiceAdd. In this event, none of the data you specify in the InvoiceAdd BillAddress/ShipAddress will be written to the invoice, including any notes. This approximates the behavior in the UI.

If you need to update the BillAddress/ShipAddress data, you can do an InvoiceMod after the InvoiceAdd.

You can make as many of these entire SalesOrder links to your invoice as you want. Just specify a separate LinkToTxnID for each one whose lines are to be pulled into the invoice. Notice that you cannot use the same TxnId in a LinktoTxnID element, and also inside the LinktoTxn aggregate. That is, you cannot link the whole SalesOrder and then specify one line item from it. You’ll get a runtime error if you do.

Excerpt from the API Reference page for the InvoiceAdd request, with the LinkToTxn aggregate circled:

Request message for an invoice that operates on all of the sales order lines and selected lines

The following QBFC sample is links an invoice to two sales order, pulling all of the lines lines from those two sales orders and also links to selected line items from two other sales orders.

Dim SessionManager As QBSessionManager
Set SessionManager = New QBSessionManager
SessionManager.OpenConnection "", "InvoiceAdd_wSalesOrder_Sample"
SessionManager.BeginSession "", omDontCare
Dim InvoiceAddSet As IMsgSetRequest
Set InvoiceAddSet = SessionManager.CreateMsgSetRequest("US", 6, 0)
Dim InvoiceSalesAdd As IInvoiceAdd
Set InvoiceSalesAdd = InvoiceAddSet.AppendInvoiceAddRq
InvoiceSalesAdd.CustomerRef.FullName.setValue "Kaushik, Laxmi"
InvoiceSalesAdd.ARAccountRef.FullName.setValue "Accounts Receivable"
InvoiceSalesAdd.IsToBeEmailed.setValue True
InvoiceSalesAdd.LinkToTxnIDList.Add "611-1197728725"
InvoiceSalesAdd.LinkToTxnIDList.Add "616-1197728784"
Dim InvoiceLineAdder As IInvoiceLineAdd
Set InvoiceLineAdder = InvoiceSalesAdd.ORInvoiceLineAddList.Append.InvoiceLineAdd
InvoiceLineAdder.Quantity.setValue 1
InvoiceLineAdder.LinkToTxn.TxnID.setValue "65F-1197730157"
InvoiceLineAdder.LinkToTxn.TxnLineID.setValue "661-1197730157"
Set InvoiceLineAdder = InvoiceSalesAdd.ORInvoiceLineAddList.Append.InvoiceLineAdd
InvoiceLineAdder.Quantity.setValue 1
InvoiceLineAdder.LinkToTxn.TxnID.setValue "665-1197730212"
InvoiceLineAdder.LinkToTxn.TxnLineID.setValue "667-1197730212"
Dim InvoiceSalesAddResp As IMsgSetResponse
Set InvoiceSalesAddResp = SessionManager.DoRequests(InvoiceAddSet)
SessionManager.EndSession
SessionManager.CloseConnection

In this example, notice the following points:

The way in which the invoice object IInvoiceAdd is returned from the AppendInvoiceAddRq method and then is set from that point.
The way each invoice line is added and constructed, with the IInvoiceLineAdd object returned and filled.
The reuse of the IInvoiceLineAdd object for multiple item lines.

Request message for an invoice that operates on multiple sales orders and specific line items

<QBXML>
<qbxmlmsgsrq onerror="stopOnError">
    <invoiceaddrq requestid="0">
        <invoiceadd>
            <customerref>
                <fullname>Kaushik, Laxmi</fullname>
            </customerref>
            <araccountref>
                <fullname>Accounts Receivable</fullname>
            </araccountref>
            <istobeemailed>1
            <linktotxnid>611-1197728725
            <linktotxnid>616-1197728784
            <invoicelineadd>
                <quantity>1</quantity>
                <linktotxn>
                    <txnid>65F-1197730157</txnid>
                    <txnlineid>661-1197730157</txnlineid>

            </linktotxn></invoicelineadd>
            <invoicelineadd>
                <quantity>1</quantity>
                <linktotxn>
                    <txnid>665-1197730212</txnid>
                    <txnlineid>667-1197730212</txnlineid>
            </linktotxn>
    </invoicelineadd>
</qbxmlmsgsrq>

Rules for linking invoices to sales orders

The rules you must follow are the same as listed above under Rules for linking item receipts and bills to purchase orders.

Why does the API Reference list LinkToTxn for unsupported transactions?

Because of the way the qbXML spec makes use of macros to ensure that common elements are consistent across multiple request types, the LinkToTxn aggregate within the ItemLineAdd aggregate also appear in the VendorCreditAdd, CheckAdd,

CreditCardChargeAdd, and CreditCardCreditAdd requests, even though these are not implemented. If you attempt to use the LinkToTxn aggregate in those requests you will get a not supported warning (statusCode 530) in your response.

Limitations of modifying bills and item receipts

You cannot link a PurchaseOrder to a Bill or ItemReceipt in the BillMod and ItemReceiptMod requests. That is, you cannot add new lines that link to a PurchaseOrder to an existing Bill or ItemReceipt. Also, when you modify transaction lines in a Bill or an ItemReceipt, you may lose links between the Bill and the PurchaseOrder or between the ItemReceipt and the PurchaseOrder. So you should be very careful before modifying transaction lines.

Querying for linked transactions

You can find transactions linked to purchase orders and sales orders by setting the IncludeLinkedTxns element to true in the purchase order or sales order query. By default, linked transactions are not returned.

However, notice that the linked transaction as a whole is returned–you get the txnID, but not any txnLineIDs. This is fine if you linked the whole transaction to your SalesOrder or PurchaseOrder. But what happens if you linked individual transaction line items to line items in your SalesOrder or PurchaseOrder? The answer to this is that you cannot retrieve that line item information so you can see which line items in the PurchaseOrder/SalesOrder came from which lines in the bill, item receipt, or invoice.

Re: “Is Manually Closed” in Purchase Orders and Sales Orders

On a purchase order, a check in the Closed column can indicate either that the items have been received in full or that the line item has been manually closed. To determine why a line item was closed, check its IsManuallyClosed field in PurchaseOrderLineRet. If this field is False, then compare the ReceivedQuantity value with the Quantity originally ordered. If the Quantity is equal to the ReceivedQuantity value, the order is fully received. Note that if you try to manually close a line that has already been fully received, you will receive an error.

The IsManuallyClosed flag on the main transaction takes precedence over the IsManuallyClosed flag on individual lines within the transaction. To avoid ambiguity, if the IsManuallyClosed flag is specified for the main transaction, do not set it for individual lines.