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 | Up to 100 Overpayments will be returned per call, with line items shown for each, when the page parameter is used e.g. page=1 |
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