A ReceivePaymentAdd may apply less than its TotalAmount, or nothing at all with IsAutoApply false, and QuickBooks keeps the rest as the payment's UnusedPayment

Observed 2026-10-30 on QuickBooks Enterprise Solutions 24.0 (US), reporting qbXML 17.0.

QuickBooks accepts a ReceivePaymentAdd whose TotalAmount is more than the amounts it applies, and one with IsAutoApply false that applies nothing. In both cases it saves the payment and keeps what was not applied as the payment's UnusedPayment. With IsAutoApply false it leaves the customer's open invoices alone.

This payment of 150.00 applied 100.00 to an invoice of 100.00:

qbXML
<ReceivePaymentAdd>
  <CustomerRef><ListID>8000004A-1793402352</ListID></CustomerRef>
  <RefNumber>QS-PAY-OVER</RefNumber>
  <TotalAmount>150.00</TotalAmount>
  <AppliedToTxnAdd>
    <TxnID>4FF0-1793402353</TxnID>
    <PaymentAmount>100.00</PaymentAmount>
  </AppliedToTxnAdd>
</ReceivePaymentAdd>

It answered status 0 (lines reduced):

qbXML
<TxnID>4FF8-1793402434</TxnID>
<RefNumber>QS-PAY-OVER</RefNumber>
<TotalAmount>150.00</TotalAmount>
<UnusedPayment>50.00</UnusedPayment>
<UnusedCredits>0.00</UnusedCredits>
<AppliedToTxnRet>
<TxnID>4FF0-1793402353</TxnID>
<TxnType>Invoice</TxnType>
<TxnDate>2026-10-30</TxnDate>
<RefNumber>QS-ASK-1</RefNumber>
<BalanceRemaining>0.00</BalanceRemaining>
<Amount>100.00</Amount>
</AppliedToTxnRet>

A second payment for the same customer applied nothing:

qbXML
<ReceivePaymentAdd>
  <CustomerRef><ListID>8000004A-1793402352</ListID></CustomerRef>
  <RefNumber>QS-PAY-UNAP</RefNumber>
  <TotalAmount>40.00</TotalAmount>
  <IsAutoApply>false</IsAutoApply>
</ReceivePaymentAdd>

It also answered status 0, with no AppliedToTxnRet:

qbXML
<TxnID>4FFD-1793402435</TxnID>
<RefNumber>QS-PAY-UNAP</RefNumber>
<TotalAmount>40.00</TotalAmount>
<UnusedPayment>40.00</UnusedPayment>
<UnusedCredits>50.00</UnusedCredits>

The customer's other open invoice of 100.00 still owed 100.00 afterwards. The UnusedCredits of 50.00 is the first payment's UnusedPayment: a payment's UnusedCredits counts the customer's other unused payments, not its own.

What to do

To record a payment that is more than an invoice owes, send the whole TotalAmount and apply only the balance; QuickBooks keeps the rest on the payment. To record a payment without touching any invoice, send IsAutoApply false and no AppliedToTxnAdd. Read UnusedPayment for what is left of this payment, and do not add UnusedCredits to it.

Not observed

  • A payment with IsAutoApply true.
  • A payment with neither IsAutoApply nor AppliedToTxnAdd, which the XSD does not allow.

QuBe Sync is a JSON API for QuickBooks Desktop that is built on what these findings show.