| URL | https://api.xero.com/api.xro/2.0/Overpayments |
| Methods Supported | GET, PUT |
| Description | Allows you to retrieve overpayments Allows you to allocate overpayments to outstanding invoices |
Use this method to retrieve Overpayments
| Type | See Overpayment Types |
| Contact | See Contacts |
| Date | The date the overpayment was made YYYY-MM-DD |
| Status | See Overpayment Status Codes |
| LineAmountTypes | See Overpayment Line Amount Types |
| LineItems | See Overpayment Line Items |
| SubTotal | The subtotal of the overpayment excluding taxes |
| TotalTax | The total tax on the overpayment |
| Total | The total of the overpayment (subtotal + total tax) |
| UpdatedDateUTC | UTC timestamp of last update to the overpayment |
| CurrencyCode | Currency used for the overpayment |
| OverpaymentID | Xero generated unique identifier |
| CurrencyRate | The currency rate for a multicurrency overpayment. If no rate is specified, the XE.com day rate is used |
| RemainingCredit | The remaining credit balance on the overpayment |
| Allocations | See Allocations |
| Payments | See Payments |
| HasAttachments | boolean to indicate if a overpayment has an attachment |
| Elements for Line Items | |
| Description | Description needs to be at least 1 char long. A line item with just a description (i.e no unit amount or quantity) can be created by specifying just a Description element that contains at least 1 character |
| Quantity | LineItem Quantity |
| UnitAmount | Lineitem unit amount. By default, unit amount will be rounded to two decimal places. You can opt in to use four decimal places by adding the querystring parameter unitdp=4 to your query. See the Rounding in Xero guide for more information. |
| AccountCode | See Accounts |
| TaxType | Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes. |
| TaxAmount | The tax amount is auto calculated as a percentage of the line amount (see below) based on the tax rate. This value can be overriden if the calculated TaxAmount is not correct. |
| LineAmount | If you wish to omit either of the Quantity or UnitAmount you can provide a LineAmount and Xero will calculate the missing amount for you. |
| Tracking | Optional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements. |
| OverpaymentID | You can specify an individual record by appending the OverpaymentID to the endpoint, i.e. GET https://.../Overpayments/{identifier} |
| Modified After | The ModifiedAfter filter is actually an HTTP header: ' If-Modified-Since'. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only overpayments created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00 |
| Where | Filter by an any element ( see Filters ) |
| order | Order by any element returned ( see Order By ) |
| page | e.g. page=1 – Up to 100 overpayments will be returned in a single API call with line items shown for each overpayment |
Example response for retrieving Overpayments
GET https://api.xero.com/api.xro/2.0/Overpayments
| Invoice | The invoice the overpayment is being allocated against |
| AppliedAmount | The amount being applied to the invoice |
| Date | The date the overpayment is applied YYYY-MM-DD (read-only). This will be the latter of the invoice date and the overpayment date. |
Example request allocating $60.50 from an RECEIVE-OVERPAYMENT to an outstanding ACCREC invoice
PUT https://api.xero.com/api.xro/2.0/Overpayments/b356e488-2678-4be4-ad4b-d294df2d48d6/Allocations
View a summary of the actions made by all users to the overpayment. See the History and Notes page for more details.
Example of retrieving an overpayment's history
GET https://api.xero.com/api.xro/2.0/Overpayments/{Guid}/History
Add a note which will appear in the history against an overpayment. See the History and Notes page for more details.
Example of creating a note against a overpayment
PUT https://api.xero.com/api.xro/2.0/Overpayments/{Guid}/History