How do Overpayments work with the Xero API?

The process of creating and allocating Overpayments works a bit differently to other Xero API endpoints. To create an Overpayment you use the BankTransactions endpoint and to allocate outstanding invoices to an Overpayment you use the Overpayments endpoint. It’s also worth noting that Overpayments can only have a single line item. The line item will be automatically coded to either the Accounts Receivable (receive) or Accounts Payable (spend) control account when uploading to Xero. Overpayments also do not have any taxable component to the line item – this is always set to no tax.

The Xero API does not currently support creating and allocating a Overpayments in a single call – the create and allocation must be done in two separate calls. The fmAccounting Link (Xero Edition) file shows how to perform these in a single FileMaker script so you can have one button that creates and allocates at the same time.

The Xero API does not currently support updates to an existing Overpayment – once you have pushed the Overpayment from FileMaker to Xero you cannot make any changes to the Overpayment, but you can upload allocations against the Overpayment.

There is also a bug with the Xero Overpayments endpoint that incorrectly shows the TaxType as ‘NONE’ in the API but displays as ‘BASEXCLUDED’ in the Xero website/UI. This is scheduled to be fixed in a future update to the Xero API.