Prepayments


Overview

URL https://api.xero.com/api.xro/2.0/Prepayments
Methods Supported GET, PUT
Description Allows you to retrieve prepayments Allows you to allocate prepayments to outstanding invoices
Create prepayments using the BankTransactions endpoint.
Refund prepayments using the Payments endpoint.

Elements for Prepayments

Type See Prepayment Types
Contact See Contacts
Date The date the prepayment is created YYYY-MM-DD
Status See Prepayment Status Codes
LineAmountTypes See Prepayment Line Amount Types
LineItems See Prepayment Line Items
SubTotal The subtotal of the prepayment excluding taxes
Total Tax The total tax on the prepayment
Total The total of the prepayment(subtotal + total tax)
UpdatedDateUTC UTC timestamp of last update to the prepayment
CurrencyCode Currency used for the prepayment
PrepaymentID Xero generated unique identifier
CurrencyRate The currency rate for a multicurrency prepayment. If no rate is specified, the XE.com day rate is used
RemainingCredit The remaining credit balance on the prepayment
Allocations See Allocations
HasAttachments boolean to indicate if a prepayment 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 Prepayments

Optional parameters for GET Prepayments

Record filter You can specify an individual record by appending the value to the endpoint, i.e. GET https://.../Prepayments/{identifier}
PrepaymentID - The Xero identifier for a prepayment 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 prepayments 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 prepayments will be returned in a single API call with line items shown for each prepayment
By default GET Prepayments responses are formatted as XML. You can also retrieve responses in JSON format.

Example response for GET Prepayments

<Prepayments>
    <Prepayment>
      <Contact>
        <ContactID>c6c7b870-bb4d-489a-921e-2f0ee4192ff9</ContactID>
        <Name>Mr Contact</Name>
      </Contact>
      <Date>2012-08-30T00:00:00</Date>
      <Status>PAID</Status>
      <LineAmountTypes>Inclusive</LineAmountTypes>
      <SubTotal>86.96</SubTotal>
      <TotalTax>13.04</TotalTax>
      <Total>100.00</Total>
      <UpdatedDateUTC>2012-08-29T23:43:01.097</UpdatedDateUTC>
      <CurrencyCode>NZD</CurrencyCode>
      <FullyPaidOnDate>2012-08-30T00:00:00</FullyPaidOnDate>
      <Type>RECEIVE-PREPAYMENT</Type>
      <PrepaymentID>aea95d78-ea48-456b-9b08-6bc012600072</PrepaymentID>
      <CurrencyRate>1.000000</CurrencyRate>
      <RemainingCredit>0.00</RemainingCredit>
      <Allocations>
        <Allocation>
          <AppliedAmount>100.00</AppliedAmount>
          <Date>2012-08-30T00:00:00</Date>
          <Invoice>
            <InvoiceID>87cfa39f-136c-4df9-a70d-bb80d8ddb975</InvoiceID>
            <InvoiceNumber>INV-0001</InvoiceNumber>
          </Invoice>
        </Allocation>
      </Allocations>
      <HasAttachments>false</HasAttachments>
  </Prepayment>
</Prepayments>

PUT Prepayments/{PrepaymentID}/Allocations

Use this endpoint to allocate part or full amounts of a prepayment to outstanding invoices.

Elements for Allocations

Invoice the invoice the prepayment is being allocated against
AppliedAmount the amount being applied to the invoice
Date the date the prepayment is applied YYYY-MM-DD (read-only). This will be the latter of the invoice date and the prepayment date.
Below is an example of allocating $60.50 from an RECEIVE-PREPAYMENT to an outstanding ACCREC invoice for the same contact. Note the URL needs to specify the prepayment that you are allocating e.g. PUT Prepayments/b356e488-2678-4be4-ad4b-d294df2d48d6/Allocations
<Allocations>
  <Allocation>
    <AppliedAmount>60.50</AppliedAmount>
    <Invoice>
      <InvoiceID>f5832195-5cd3-4660-ad3f-b73d9c64f263</InvoiceID>
    </Invoice>
  </Allocation>
</Allocations>

Prepayments Demo

A demonstration of prepayments and overpayments including a walkthrough on how to create a prepayment and assign it to an invoice using the API.