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.

GET Prepayments

Use this method to retrieve 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
Reference Returns Invoice # field. Reference field isn't available.
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
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 Prepayments

PrepaymentID You can specify an individual record by appending the PrepaymentID to the endpoint, i.e. GET https://.../Prepayments/{identifier}
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

Example response for retrieving Prepayments

GET https://api.xero.com/api.xro/2.0/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.

Example request allocating $60.50 from an RECEIVE-PREPAYMENT to an outstanding ACCREC invoice

PUT https://api.xero.com/api.xro/2.0/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.