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

Elements for Overpayments

Type See Overpayment Types
Contact See Contacts
Date The date the overpayment is created 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

All of these elements are returned on a GET request.
<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.

GET Overpayments

Optional parameters for GET Overpayments

Record filter You can specify an individual record by appending the value to the endpoint, i.e. GET https://.../Overpayments/{identifier}
OverpaymentID - The Xero identifier for an overpayment e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
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
By default GET Overpayments responses are formatted as XML. You can also retrieve responses in JSON format.

Example response for GET 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.

Below is an example of allocating $60.50 from an RECEIVE-OVERPAYMENT to an outstanding ACCREC invoice for the same contact. Note the URL needs to specify the overpayment that you are allocating e.g. PUT 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.