Overpayments


Overview

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
Create Overpayments using the BankTransactions endpoint.
Refund Overpayments using the Payments endpoint

GET Overpayments

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.

Optional parameters for GET Overpayments

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
<Overpayments>
  <Overpayment>
    <Contact>
      <ContactID>c6c7b870-bb4d-489a-921e-2f0ee4192ff9</ContactID>
      <Name>Mr Contact</Name>
    </Contact>
    <Date>2015-03-30T00:00:00</Date>
    <Status>PAID</Status>
    <LineAmountTypes>Inclusive</LineAmountTypes>
    <SubTotal>86.96</SubTotal>
    <TotalTax>13.04</TotalTax>
    <Total>100.00</Total>
    <UpdatedDateUTC>2015-03-29T23:43:01.097</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <Type>RECEIVE-OVERPAYMENT</Type>
    <OverpaymentID>aea95d78-ea48-456b-9b08-6bc012600072</OverpaymentID>
    <CurrencyRate>1.000000</CurrencyRate>
    <RemainingCredit>0.00</RemainingCredit>
    <Allocations>
      <Allocation>
        <AppliedAmount>100.00</AppliedAmount>
        <Date>2015-03-30T00:00:00</Date>
        <Invoice>
          <InvoiceID>87cfa39f-136c-4df9-a70d-bb80d8ddb975</InvoiceID>
          <InvoiceNumber>INV-0001</InvoiceNumber>
        </Invoice>
      </Allocation>
    </Allocations>
    <HasAttachments>false</HasAttachments>
  </Overpayment>
</Overpayments>

PUT Overpayments/{OverpaymentID}/Allocations

Use this endpoint to allocate part or full amounts of an overpayment to outstanding invoices.

Elements for Allocations

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
<Allocations>
  <Allocation>
    <AppliedAmount>60.50</AppliedAmount>
    <Invoice>
      <InvoiceID>f5832195-5cd3-4660-ad3f-b73d9c64f263</InvoiceID>
    </Invoice>
  </Allocation>
</Allocations>

Overpayments Demo

A demonstration of prepayments and overpayments including a walkthrough on how to create an overpayment and refund it using the API.