Requests that define and use macros

A situation that often arises when an application is building a message request set is the need to create an object, typically a transaction object, in one request and then refer to that object in another request later in the same message request set, or later in the same session. For example, it might be necessary to create an invoice in one request and then apply a payment to that invoice in a subsequent request. Or to create a DepositAdd transaction in one request and follow it with a ClearedStatusMod request. The SDK supports this with a macro mechanism that allows applications to define macros for object IDs as part of the request message that creates the object and then use the macro to refer to the object in subsequent requests, within the same message set, that operate on the newly created object.

In the first case mentioned above, the InvoiceAddRq would include a tag like the following:

<InvoiceAdd defMacro="TxnID:1234">

Later in the message set, the ReceivePaymentAddRq would use a tag like this to reference the invoice:

<TxnID useMacro="TxnID:1234"></TxnID>

The following shows an InvoiceAddRq message followed by a ReceivePaymentAddRq. A macro is defined in the InvoiceAddRq message to enable the ReceivePaymentAddRq to apply a payment to the invoice that was created by the InvoiceAddRq:

<QBXMLMsgsRq onError = "stopOnError">
  <InvoiceAddRq requestID = "695">
    <InvoiceAdd defMacro="TxnID:1234">
      <CustomerRef>
        <FullName>Jones</FullName>
      </CustomerRef>
      <TxnDate>2002-08-29</TxnDate>
      <RefNumber>123-ABC</RefNumber>
      <InvoiceLineAdd>
        <ItemRef>
          <FullName>Services</FullName>
        </ItemRef>
        <Desc>For the house</Desc>
        <Quantity>1</Quantity>
        <Rate>120.00</Rate>
      </InvoiceLineAdd>
    </InvoiceAdd>
  </InvoiceAddRq>
  ...
  <ReceivePaymentAddRq requestID = "UUIDTYPE">
    <ReceivePaymentAdd>
      <CustomerRef>
        <FullName>Jones</FullName>
      </CustomerRef>
      <TotalAmount>20.00</TotalAmount>
      <AppliedToTxnAdd>
        <TxnID useMacro="TxnID:1234"></TxnID>
        <PaymentAmount>20.00</PaymentAmount>
      </AppliedToTxnAdd>
    </ReceivePaymentAdd>
  </ReceivePaymentAddRq>
</QBXMLMsgsRq>

This example shows a DepositAddRq message followed by two ClearedStatusModRqs. Two macros are defined in the DepositAddRq message, which enables the ClearedStatusModRqs to clear both the deposit and the cash back:

<DepositAddRq requestID = "695">
  <DepositAdd defMacro="TxnID:66">
    <TxnDate>2002-09-12</TxnDate>
    <DepositToAccountRef>
      <FullName>Jones</FullName>
    </DepositToAccountRef>
    <CashBackInfoAdd defMacro="TxnLineID:33">
      <AccountRef>
        <FullName>Savings</FullName>
      </AccountRef>
      <Amount>5.00</Amount>
    </CashBackInfoAdd>
    <DepositLineAdd>
      <EntityRef>
        <FullName>Smith</FullName>
      </EntityRef>
      <AccountRef>
        <FullName>other</FullName>
      </AccountRef>
      <CheckNumber>1986</CheckNumber>
      <Amount>20.00</Amount>
    </DepositLineAdd>
  </DepositAdd>
</DepositAddRq>
...
<ClearedStatusModRq requestID = "5629">
  <ClearedStatusMod>
    <TxnID useMacro="TxnID:66"></TxnID>
    <ClearedStatus>Cleared</ClearedStatus>
  </ClearedStatusMod>
</ClearedStatusModRq>
...
<ClearedStatusModRq requestID = "8411">
  <ClearedStatusMod>
    <TxnID useMacro="TxnID:66"></TxnID>
    <TxnLineID useMacro="TxnLineID:33">2</TxnLineID>
    <ClearedStatus>Cleared</ClearedStatus>
  </ClearedStatusMod>
</ClearedStatusModRq>

Macros are generally defined in messages that create transaction objects, for the TxnID and TxnLineID elements that will identify those transaction in subsequent requests. Macros are generally used in subsequent requests to identify the newly created objects, particularly in the following ID-type elements of the subsequent requests:

• PaymentTxnID
• PaymentTxnLineID
• TxnID
• TxnLineID

The API Reference shows which request messages have the defMacro and useMacro capabilities. The following reference page for the DepositAddRq message shows how the defMacro capability is indicated for the IDepositAdd (qbXML name <depositAdd>) and DepositLineAddList (qbXML name <DepositLineAddList>) message elements.

The following shows how the useMacro capability is indicated for the TxnID (qbXML element <depositAdd>) and TxnLineID (qbXML element <DepositLineAddList>) message elements.

The macro names used in the examples on this page follow the convention of a tagname (“TxnID”) followed by a name (“1234”). The choice of tagname is up to you, enabling you to construct macro names that are meaningful for your applications. The following restrictions apply to macro names:

• Macro names are limited to 40 characters.
• Macro names can include any alphanumeric character, as well as the dash (-) and underscore (_) characters.
• Macro names must be unique during an SDK-to-QuickBooks session: Once a macro has been defined, it is stored until the session is ended.
• Each use of the defMacro attribute supports only one tagname/name combination. (For example, defMacro=”TxnID:1234;TxnLineID:5678” would be invalid.)