Skip to content
 

Developer

See all pages
Try Xero Free

Invoices

URL https://api.xero.com/api.xro/2.0/Invoices
Methods Supported GET, PUT, POST
Description Allows you to retrieve any invoices
Allows you to add or update draft invoices
Allows you to add approved invoices
Allows you to delete draft invoices
Allows you to void approved invoices

Elements for Invoices

The following are mandatory for a PUT / POST request
<Type> See Invoice Types
<Contact> See Contacts
The following are mandatory to create an approved invoice
<Type> See Invoice Types
<Contact> See Contacts
<Lineitems> See LineItems
<Date> Date invoice was issued – YYYY-MM-DD
<DueDate> Date invoice is due – YYYY-MM-DD
The following are recommended for a PUT / POST request
<LineAmountTypes> See Line Amount Types
<LineItems> See Line items
The following are optional for a PUT / POST request
<InvoiceNumber> ACCREC – Unique alpha numeric code identifying invoice (when missing will auto-generate from your Organisation Invoice Settings)
ACCPAY – non-unique alpha numeric code identifying invoice
<Reference> ACCREC only – additional reference number
<BrandingThemeID> See BrandingThemes
<Url> URL link to a source document – shown as "Go to [appName]" in the Xero app
<CurrencyCode> The currency that invoice has been raised in (see Currencies)
<Status> See Invoice Status Codes
<SubTotal> Total of invoice excluding taxes
<TotalTax> Total tax on invoice
<Total> Total of Invoice tax inclusive (i.e. SubTotal + TotalTax)
The following are only returned on a GET request
<InvoiceID> Xero generated unique identifier for invoice
<Payments> See Payments
<AmountDue> Amount remaining to be paid on invoice
<AmountPaid> Sum of payments received for invoice
<AmountCredited> Sum of all credit notes, over-payments and pre-payments applied to invoice
<UpdatedDateUTC> Last modified date UTC format
<SentToContact> boolean to indicate if an invoice has been sent to a contact via the Xero app
<CreditNotes> Details of credit notes that have been applied to an invoice

Elements for Line Items
The <LineItems> element can contain any number of individual <LineItem> sub-elements. At least one is required to create a complete Invoice.

All of these elements are returned on a GET request.
The following elements are required to create an approved invoice
<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> Quantity must be >=0
<UnitAmount> Lineitem unit amount
<AccountCode> AccountCode must be active for the organisation
The following are recommended for a PUT / POST request
<Description> LineItem Description
<Quantity> LineItem Quantity
<UnitAmount> LineItem Unit Amount
<ItemCode> See Items
<AccountCode> See Accounts
The following are optional for a PUT / POST request
<TaxType> Used as an override if the default Tax Code for the selected <AccountCode> is not correct – see TaxTypes.
<TaxAmount> Used as an override 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.

POST Invoices

Use this method to create or update an invoice with either a DRAFT, SUBMITTED or AUTHORISED status by specifying the Status element in your request.

Example of minimum elements required to add a new draft AR invoice to ABC Limited with no line items and a status of DRAFT(default)

<Invoice>
  <Type>ACCREC</Type>
  <Contact>
    <Name>ABC Limited</Name>
  </Contact>
</Invoice>

Example of a draft AR invoice with enough detail to be approved once it’s been created.

<Invoice>
  <Type>ACCREC</Type>
  <Contact>
    <Name>ABC Limited</Name>
  </Contact>
  <Date>2009-08-30</Date>
  <DueDate>2009-09-20</DueDate>
  <LineAmountTypes>Exclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Consulting services as agreed</Description>
      <Quantity>5.0000</Quantity>
      <UnitAmount>120.00</UnitAmount>
      <AccountCode>200</AccountCode>
    </LineItem>
  </LineItems>
</Invoice>

Example of minimum elements required to add an approved AR invoice to ABC Limited

<Invoice>
 <Type>ACCREC</Type>
 <Contact><Name>ABC Limited</Name></Contact>
 <DueDate>2011-07-20</DueDate>
 <LineItems>
 <LineItem>
  <Description>Services as agreed </Description><Quantity>4</Quantity><UnitAmount>100.00</UnitAmount><AccountCode>200</AccountCode>
 </LineItem>
</LineItems>
<Status>AUTHORISED</Status>
</Invoice>

Example of an invoice inclusive of Tax in USD when the base currency of the org is NZD. This example also assigns a tracking category to a line item

<Invoice>
  <Type>ACCREC</Type>
  <CurrencyCode>USD</CurrencyCode>
  <Contact>
    <Name>ABC Limited</Name>
  </Contact>
  <Date>2009-08-30</Date>
  <DueDate>2009-09-20</DueDate>
  <LineAmountTypes>Inclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Consulting services as agreed</Description>
      <Quantity>5.0000</Quantity>
      <UnitAmount>99</UnitAmount>
      <AccountCode>200</AccountCode>
      <Tracking>
          <TrackingCategory>
            <Name>Activity/Workstream</Name>
            <Option>Onsite consultancy</Option>
          </TrackingCategory>
      </Tracking>
    </LineItem>
  </LineItems>
</Invoice>

Example of a draft AR invoice using an item code of 2010-SWEATER-RED. NB The price and account code of the item are not given so the default sales price and account code on the item list will be used. If the UnitAmount and AccountCode element is specified then this will overide the UnitPrice value defined for the item in the item list. 

<Invoice>
  <Type>ACCREC</Type>
  <Contact>
    <Name>ABC Limited</Name>
  </Contact>
  <Date>2009-08-30</Date>
  <DueDate>2009-09-20</DueDate>
  <LineAmountTypes>Exclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Red Sweater</Description>
      <Quantity>5</Quantity>
      <ItemCode>2010-SWEATER-RED</ItemCode>
    </LineItem>
  </LineItems>
</Invoice>

Example of an invoice with every single element being specified, including the full record to enabling update to Contact record with 1 single API request:

<Invoices>
  <Invoice>
    <Type>ACCREC</Type>
    <Contact>
      <ContactNumber>0006841301</ContactNumber>
      <Name>Ariki Properties</Name>
      <ContactStatus>ACTIVE</ContactStatus>
      <EmailAddress>emailaddress@yourdomain.com</EmailAddress>
      <SkypeUserName>Skype Name/Number</SkypeUserName>
      <BankAccountDetails>Bank Account Details</BankAccountDetails>
      <TaxNumber>Tax ID Number</TaxNumber>
      <AccountsReceivableTaxType>OUTPUT</AccountsReceivableTaxType>
      <AccountsPayableTaxType>INPUT</AccountsPayableTaxType>
      <FirstName>Simon</FirstName>
      <LastName>Greenville</LastName>
      <DefaultCurrency>USD</DefaultCurrency>
      <Addresses>
        <Address>
          <AddressType>POBOX</AddressType>
          <AttentionTo>Simon G.</AttentionTo>
          <AddressLine1>PO Box 10112</AddressLine1>
          <AddressLine2></AddressLine2>
          <AddressLine3></AddressLine3>
          <AddressLine4></AddressLine4>
          <City>New York</City>
          <Region>New York State</Region>
          <PostalCode>10112</PostalCode>
          <Country>USA</Country>
        </Address>
        <Address>
          <AddressType>STREET</AddressType>
          <AttentionTo>Simon G.</AttentionTo>
          <AddressLine1>Level 71</AddressLine1>
          <AddressLine2>30 Rockefeller plaza</AddressLine2>
          <AddressLine3></AddressLine3>
          <AddressLine4></AddressLine4>
          <City>New York</City>
          <Region>New York State</Region>
          <PostalCode>10112</PostalCode>
          <Country>USA</Country>
        </Address>
      </Addresses>
      <Phones>
        <Phone>
          <PhoneType>DEFAULT</PhoneType>
          <PhoneNumber>5996999</PhoneNumber>
          <PhoneAreaCode>877</PhoneAreaCode>
          <PhoneCountryCode>0001</PhoneCountryCode>
        </Phone>
        <Phone>
          <PhoneType>DDI</PhoneType>
          <PhoneNumber>1234567</PhoneNumber>
          <PhoneAreaCode>877</PhoneAreaCode>
          <PhoneCountryCode>0001</PhoneCountryCode>
        </Phone>
        <Phone>
          <PhoneType>FAX</PhoneType>
          <PhoneNumber>7654321</PhoneNumber>
          <PhoneAreaCode>877</PhoneAreaCode>
          <PhoneCountryCode>0001</PhoneCountryCode>
        </Phone>
        <Phone>
          <PhoneType>MOBILE</PhoneType>
          <PhoneNumber>5555555</PhoneNumber>
          <PhoneAreaCode>877</PhoneAreaCode>
          <PhoneCountryCode>0001</PhoneCountryCode>
        </Phone>
      </Phones>
    </Contact>
    <Date>2009-09-08T00:00:00</Date>
    <DueDate>2009-10-20T00:00:00</DueDate>
    <InvoiceNumber>OIT:01065</InvoiceNumber>
    <Reference>Ref:SMITHK</Reference>
    <BrandingThemeID>3b148ee0-adfa-442c-a98b-9059a73e8ef5</BrandingThemeID>
    <Url>http://www.accounting20.com</Url>
    <CurrencyCode>NZD</CurrencyCode>
    <Status>SUBMITTED</Status>
    <LineAmountTypes>Inclusive</LineAmountTypes>
    <SubTotal>87.11</SubTotal>
    <TotalTax>10.89</TotalTax>
    <Total>98.00</Total>
    <LineItems>
      <LineItem>
        <Description>3 copies of OS X 10.6 Snow Leopard</Description>
        <Quantity>3.0000</Quantity>
        <UnitAmount>59.00</UnitAmount>
        <TaxType>OUTPUT</TaxType>
        <TaxAmount>19.67</TaxAmount>
        <LineAmount>177.00</LineAmount>
        <AccountCode>200</AccountCode>
        <Tracking>
          <TrackingCategory>
            <TrackingCategoryID>e2f2f732-e92a-4f3a-9c4d-ee4da0182a13</TrackingCategoryID>
            <Name>Region</Name>
            <Option>North</Option>
          </TrackingCategory>
        </Tracking>
      </LineItem>
      <LineItem>
        <Description>Returned Apple Keyboard with Numeric Keypad (faulty)</Description>
        <Quantity>1.0000</Quantity>
        <UnitAmount>-79.00</UnitAmount>
        <TaxType>OUTPUT</TaxType>
        <TaxAmount>-8.78</TaxAmount>
        <LineAmount>-79.00</LineAmount>
        <AccountCode>200</AccountCode>
        <Tracking />
      </LineItem>
    </LineItems>
  </Invoice>
</Invoices>

If you are entering many invoices in a single API call then we recommend you utilise our new response format that shows validation errors for each invoice. The new response messages for validating bulk API calls would mean a breaking change so to utilise this functionality you’ll need to append ?SummarizeErrors=false to the end of your API calls e.g. POST /api.xro/2.0/Invoices?SummarizeErrors=false

Below is an example of the altered response format. Note that each Invoice is now returned with a status element which will either contain the value OK or ERROR. If an invoice has a error then one or more validation errors will be returned. 

<Response>
  <Invoices>
    <Invoice status="OK">
      ...
    </Invoice>
    <Invoice status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </Invoice>
    <Invoice status="OK">
      ...
    </Invoice>
</Invoices>
</Response>

Example of voiding an approved invoice that has no payments applied to it.

<Invoice>
  <InvoiceNumber>INV-123</InvoiceNumber>
  <Status>VOIDED</Status>
</Invoice>

Example of deleting a draft invoice.

<Invoice>
  <InvoiceNumber>INV-239</InvoiceNumber>
  <Status>DELETED</Status>
</Invoice>

PUT Invoices

The PUT method is similar to the POST Invoices method, however you can only create new invoices with this method.

GET Invoices

Use this method to retrieve either one or many invoices.

Optional parameters

Record filter You can specify an individual record by appending the value to the endpoint, i.e.
GET https://…/Invoices/{identifier}
InvoiceID – The Xero identifier for an Invoice
e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
InvoiceNumber – The InvoiceNumber
e.g. INV-01514
Modified After The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘.
A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only invoices 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)

Line amounts are exclusive of tax by default if you don’t specify this element

By default GET Invoices responses are formatted as XML. You can also retrieve responses in JSON format. Individual invoices (e.g. Invoices/97c2dc5-cc47-4afd-8ec8-74990b8761e9) can also be returned as PDF’s see our HTTP GET documentation

Examples for GET Invoices

Example 1. This is an example response when a filter has been applied to request just a single invoice. In this case the InvoiceNumber of OIT00546 was specified. NB The response format is more detailed compared with when multiple invoices are returned. This response includes full contact details and line items.

<Invoices>
  <Invoice>
    <Type>ACCREC</Type>
    <Contact>
      <ContactID>025867f1-d741-4d6b-b1af-9ac774b59ba7</ContactID>
      <ContactStatus>ACTIVE</ContactStatus>
      <Name>City Agency</Name>
      <Addresses>
        <Address>
          <AddressType>STREET</AddressType>
        </Address>
        <Address>
          <AddressType>POBOX</AddressType>
          <AddressLine1>L4, CA House</AddressLine1>
          <AddressLine2>14 Boulevard Quay</AddressLine2>
          <City>Wellington</City>
          <PostalCode>6012</PostalCode>
        </Address>
      </Addresses>
      <Phones>
        <Phone>
          <PhoneType>DEFAULT</PhoneType>
        </Phone>
        <Phone>
          <PhoneType>DDI</PhoneType>
        </Phone>
        <Phone>
          <PhoneType>MOBILE</PhoneType>
        </Phone>
        <Phone>
          <PhoneType>FAX</PhoneType>
        </Phone>
      </Phones>
      <UpdatedDateUTC>2009-08-15T00:18:43.473</UpdatedDateUTC>
      <IsSupplier>false</IsSupplier>
      <IsCustomer>true</IsCustomer>
    </Contact>
    <Date>2009-05-27T00:00:00</Date>
    <DueDate>2009-06-06T00:00:00</DueDate>
    <Status>AUTHORISED</Status>
    <LineAmountTypes>Exclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Onsite project management </Description>
        <Quantity>1.0000</Quantity>
        <UnitAmount>1800.00</UnitAmount>
        <TaxType>OUTPUT</TaxType>
        <TaxAmount>225.00</TaxAmount>
        <LineAmount>1800.00</LineAmount>
        <AccountCode>200</AccountCode>
        <Tracking>
          <TrackingCategory>
            <TrackingCategoryID>e2f2f732-e92a-4f3a9c4d-ee4da0182a13</TrackingCategoryID>
            <Name>Activity/Workstream</Name>
            <Option>Onsite consultancy</Option>
          </TrackingCategory>
        </Tracking>
      </LineItem>
    </LineItems>
    <SubTotal>1800.00</SubTotal>
    <TotalTax>225.00</TotalTax>
    <Total>2025.00</Total>
    <UpdatedDateUTC>2009-08-15T00:18:43.457</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <InvoiceID>243216c5-369e-4056-ac67-05388f86dc81</InvoiceID>
    <InvoiceNumber>OIT00546</InvoiceNumber>
    <Payments>
      <Payment>
        <Date>2009-09-01T00:00:00</Date>
        <Amount>1000.00</Amount>
        <PaymentID>0d666415-cf77-43fa-80c7-56775591d426</PaymentID>
      </Payment>
    </Payments>
    <AmountDue>1025.00</AmountDue>
    <AmountPaid>1000.00</AmountPaid>
    <AmountCredited>0.00</AmountCredited>
  </Invoice>
</Invoices>

Example 2. Notice the subtle differences from the example above. As many invoices are being returned only a summary of the contact is returned and no line details are returned – this is to keep the response more compact. 

<Invoices>
  <Invoice>
    <Type>ACCREC</Type>
    <Contact>
      <ContactID>025867f1-d741-4d6b-b1af-9ac774b59ba7</ContactID>
        <Name>City Agency</Name>
    </Contact>
    <Date>2009-05-27T00:00:00</Date>
    <DueDate>2009-06-06T00:00:00</DueDate>
    <Status>AUTHORISED</Status>
    <LineAmountTypes>Exclusive</LineAmountTypes>
    <SubTotal>1800.00</SubTotal>
    <TotalTax>225.00</TotalTax>
    <Total>2025.00</Total>
    <UpdatedDateUTC>2009-08-15T00:18:43.457</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <InvoiceID>243216c5-369e-4056-ac67-05388f86dc81</InvoiceID>
    <InvoiceNumber>OIT00546</InvoiceNumber>
    <AmountDue>2025.00</AmountDue>
    <AmountPaid>0.00</AmountPaid>
    <AmountCredited>0.00</AmountCredited>
  </Invoice>
  <Invoice>
    <Reference>RPT-DD</Reference>
    <Type>ACCREC</Type>
    <Contact>
      <ContactID>06638157-fdfa-47f4-91d0-875b5f5c18c6</ContactID>
      <Name>Marine Systems</Name>
    </Contact>
    <Date>2009-04-26T00:00:00</Date>
    <DueDate>2009-04-26T00:00:00</DueDate>
    <Status>AUTHORISED</Status>
    <LineAmountTypes>Exclusive</LineAmountTypes>
    <SubTotal>28.50</SubTotal>
    <TotalTax>3.56</TotalTax>
    <Total>32.06</Total>
    <UpdatedDateUTC>2009-08-14T21:04:58.09</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <InvoiceID>03778e72-d541-404a-ab9b-2757aeda76a3</InvoiceID>
    <InvoiceNumber>OIT00542</InvoiceNumber>
    <AmountDue>32.06</AmountDue>
    <AmountPaid>0.00</AmountPaid>
    <AmountCredited>0.00</AmountCredited>
  </Invoice>
</Invoices>