Invoices

Overview

URL https://api.xero.com/api.xro/2.0/Invoices
Methods Supported GET, PUT, POST
Description Retrieve sales invoices or purchase bills
Create sales invoices or purchase bills
Update draft or submitted sales invoices or purchase bills
Delete draft sales invoices or purchase bills
Void approved sales invoices or purchase bills
Retrieve the online invoice Url for sales invoices
Attach files to sales invoices or purchase bills

GET Invoices

Use this method to retrieve one or many invoices.

  • By default responses are formatted as XML. You can also retrieve responses in JSON format.
  • When you retrieve multiple invoices, only a summary of the contact is returned and no line details are returned - this is to keep the response more compact.
  • The line item details will be returned when you retrieve an individual invoice, either by specifying Invoice ID or Invoice Number or by using the optional paging parameter (below).
  • Individual invoices (e.g. Invoices/97c2dc5-cc47-4afd-8ec8-74990b8761e9) can also be returned as PDF's see our HTTP GET documentation

The following elements are returned in the Invoices response

Type See Invoice Types
Contact See Contacts
Date Date invoice was issued - YYYY-MM-DD
DueDate Date invoice is due - YYYY-MM-DD
Status See Invoice Status Codes
LineAmountTypes See Line Amount Types
LineItems See LineItems. The LineItems collection can contain any number of individual LineItem sub-elements.
SubTotal Total of invoice excluding taxes
TotalTax Total tax on invoice
Total Total of Invoice tax inclusive (i.e. SubTotal + TotalTax)
TotalDiscount Total of discounts applied on the invoice line items
UpdatedDateUTC Last modified date UTC format
CurrencyCode The currency that invoice has been raised in (see Currencies)
CurrencyRate The currency rate for a multicurrency invoice
InvoiceID Xero generated unique identifier for invoice
InvoiceNumber ACCREC - Unique alpha numeric code identifying invoice
ACCPAY - non-unique alpha numeric code identifying invoice. This value will also display as Reference in the UI.
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
SentToContact Boolean to indicate whether the invoice in the Xero app displays as "sent"
ExpectedPaymentDate Shown on sales invoices (Accounts Receivable) when this has been set
PlannedPaymentDate Shown on bills (Accounts Payable) when this has been set
HasAttachments boolean to indicate if an invoice has an attachment
Payments See Payments
CreditNotes Details of credit notes that have been applied to an invoice
Prepayments See Prepayments
Overpayments See Overpayments
AmountDue Amount remaining to be paid on invoice
AmountPaid Sum of payments received for invoice
FullyPaidOnDate The date the invoice was fully paid. Only returned on fully paid invoices
AmountCredited Sum of all credit notes, over-payments and pre-payments applied to invoice
Elements for LineItems
Description The description of the line item
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.
ItemCode See Items
AccountCode See Accounts
LineItemID The Xero generated identifier for a LineItem
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 based on the tax rate
LineAmount The line amount reflects the discounted price if a DiscountRate has been used i.e LineAmount = Quantity * Unit Amount * ((100 - DiscountRate)/100)
DiscountRate Percentage discount being applied to a line item (only supported on ACCREC invoices - ACC PAY invoices and credit notes in Xero do not support discounts
Tracking Section for optional Tracking Category - see TrackingCategory. Any LineItem can have a maximum of 2 TrackingCategory elements.
Elements for TrackingCategory
Name Name of the tracking category
TrackingCategoryID Xero assigned unique ID for the category
OptionName Name of the option (required)

Example response when retrieving a single invoice

GET https://api.xero.com/api.xro/2.0/Invoices/243216c5-369e-4056-ac67-05388f86dc81

<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>
        <LineItemID>52208ff9-528a-4985-a9ad-b2b1d4210e38</LineItemID>
      </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>

Examples response when retrieving a collection of invoices without paging

GET https://api.xero.com/api.xro/2.0/Invoices

<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>

Optional parameters for GET Invoices

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
IDs, InvoiceNumbers, ContactIDs, Statuses Filter by a comma-separated list of InvoicesIDs, InvoiceNumbers, ContactIDs or Statuses. For faster response times we recommend using these explicit parameters instead of passing OR conditions into the Where filter.
e.g. GET https://.../Invoices?Statuses=DRAFT,SUBMITTED
Where Filter by any top-level element (see Filters). If possible, we recommend you limit filtering to the following optimised elements Status, InvoiceID, InvoiceNumber, Date, Reference, Contact.ContactID, Contact.Name, Contact.ContactNumber and Type. The most efficient queries are simple "==" on these fields. Using more complicated logic (e.g. OR) will slow down queries, especially on larger organisations.
order Order by any element returned (see Order By)
page e.g. page=1 – Up to 100 invoices will be returned in a single API call with line items shown for each invoice

Paging invoices (recommended)

To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned.

By using paging all the line item details for each invoice are returned which may avoid the need to retrieve each individual invoice.

Examples response when retrieving a collection of invoices using paging

GET https://api.xero.com/api.xro/2.0/Invoices?page=1

<Invoices>
  <Invoice>
    <Contact>
      <ContactID>9b9ba9e5-e907-4b4e-8210-54d82b0aa479</ContactID>
      <Name>PowerDirect</Name>
    </Contact>
    <Date>2013-05-24T00:00:00</Date>
    <DueDate>2013-06-03T00:00:00</DueDate>
    <Status>VOIDED</Status>
    <LineAmountTypes>Inclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Monthly electricity</Description>
        <UnitAmount>77.39</UnitAmount>
        <TaxType>INPUT2</TaxType>
        <TaxAmount>11.61</TaxAmount>
        <LineAmount>77.39</LineAmount>
        <AccountCode>445</AccountCode>
        <Quantity>1.0000</Quantity>
        <LineItemID>9361c7b9-7f85-44f6-9ce0-1225d63a36bd</LineItemID>
      </LineItem>
    </LineItems>
    <SubTotal>77.39</SubTotal>
    <TotalTax>11.61</TotalTax>
    <Total>89.00</Total>
    <UpdatedDateUTC>2010-11-12T12:55:16.347</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <Type>ACCPAY</Type>
    <InvoiceID>22b3fab4-ef56-4d70-a110-a7cc3c1a26cd</InvoiceID>
    <InvoiceNumber>Elec.</InvoiceNumber>
    <AmountDue>0.00</AmountDue>
    <AmountPaid>0.00</AmountPaid>
    <AmountCredited>0.00</AmountCredited>
    <CurrencyRate>1.000000</CurrencyRate>
  </Invoice>
  <Invoice>
    <Contact>
      <ContactID>9b9ba9e5-e907-4b4e-8210-54d82b0aa479</ContactID>
      <Name>PowerDirect</Name>
    </Contact>
    <Date>2013-01-21T00:00:00</Date>
    <DueDate>2013-02-01T00:00:00</DueDate>
    <Status>PAID</Status>
    <LineAmountTypes>Inclusive</LineAmountTypes>
    <LineItems>
      <LineItem>
        <Description>Monthly electricity</Description>
        <UnitAmount>78.26</UnitAmount>
        <TaxType>INPUT2</TaxType>
        <TaxAmount>11.74</TaxAmount>
        <LineAmount>78.26</LineAmount>
        <AccountCode>445</AccountCode>
        <Quantity>1.0000</Quantity>
        <LineItemID>ba9d40de-2da8-4288-80ed-a7ececa5a343</LineItemID>
      </LineItem>
    </LineItems>
    <SubTotal>78.26</SubTotal>
    <TotalTax>11.74</TotalTax>
    <Total>90.00</Total>
    <UpdatedDateUTC>2010-11-12T14:28:14.303</UpdatedDateUTC>
    <CurrencyCode>NZD</CurrencyCode>
    <FullyPaidOnDate>2013-01-31T00:00:00</FullyPaidOnDate>
    <Type>ACCPAY</Type>
    <InvoiceID>96988e67-ecf9-466d-bfbf-0afa1725a649</InvoiceID>
    <InvoiceNumber>RPT445-1</InvoiceNumber>
    <Payments>
      <Payment>
        <PaymentID>0a0ef7ee-7b91-46fa-8136-c4cc6287273a</PaymentID>
        <Date>2013-01-31T00:00:00</Date>
        <Amount>90.00</Amount>
        <CurrencyRate>1.000000</CurrencyRate>
      </Payment>
    </Payments>
    <AmountDue>0.00</AmountDue>
    <AmountPaid>90.00</AmountPaid>
    <AmountCredited>0.00</AmountCredited>
    <CurrencyRate>1.000000</CurrencyRate>
  </Invoice>
  ...
</Invoices>

Retrieving the online invoice url

To integrate your application with Xero's online invoicing, you can retrieve the online invoice url for sales (ACCREC) invoices. Note: you cannot retrieve an online invoice url for DRAFT invoices.



Example for retrieving an online invoice url

GET https://api.xero.com/api.xro/2.0/Invoices/9b9ba9e5-e907-4b4e-8210-54d82b0aa479/OnlineInvoice

<OnlineInvoices>
  <OnlineInvoice>
    <OnlineInvoiceUrl>https://in.xero.com/iztKMjyAEJT7MVnmruxgCdIJUDStfRgmtdQSIW13</OnlineInvoiceUrl>
  </OnlineInvoice>
</OnlineInvoices>

POST Invoices

Use this method to create or update an invoice

The following are required to create a draft invoice
Type See Invoice Types
Contact See Contacts
LineItems See LineItems. The LineItems collection can contain any number of individual LineItem sub-elements. At least one is required to create a complete Invoice.
The following are optional when creating or updating invoices
Date Date invoice was issued - YYYY-MM-DD. If the Date element is not specified it will default to the current date based on the timezone setting of the organisation
DueDate Date invoice is due - YYYY-MM-DD
LineAmountTypes Line amounts are exclusive of tax by default if you don't specify this element. See Line Amount Types
InvoiceNumber ACCREC - Unique alpha numeric code identifying invoice (when missing will auto-generate from your Organisation Invoice Settings) (max length = 255)
ACCPAY - non-unique alpha numeric code identifying invoice. This value will also display as Reference in the UI. (max length = 255)
Reference ACCREC only - additional reference number (max length = 255)
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)
CurrencyRate The currency rate for a multicurrency invoice. If no rate is specified, the XE.com day rate is used. (max length = [18].[6])
Status See Invoice Status Codes
SentToContact Boolean to set whether the invoice in the Xero app should be marked as "sent". This can be set only on invoices that have been approved
ExpectedPaymentDate Shown on sales invoices (Accounts Receivable) when this has been set
PlannedPaymentDate Shown on bills (Accounts Payable) when this has been set
Elements for LineItems
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 (max length = 4000)
Quantity LineItem Quantity (max length = 13)
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.
ItemCode See Items
AccountCode See Accounts
LineItemID The Xero generated identifier for a LineItem. It is recommended that you include LineItemIDs on update requests. If LineItemIDs are not included with line items in an update request then the line items are deleted and recreated.
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 The line amount reflects the discounted price if a DiscountRate has been used i.e LineAmount = Quantity * Unit Amount * ((100 - DiscountRate)/100) (can't exceed 9,999,999,999.99 )
DiscountRate Percentage discount being applied to a line item (only supported on ACCREC invoices - ACC PAY invoices and credit notes in Xero do not support discounts
Tracking Section for optional Tracking Category - see TrackingCategory. Any LineItem can have a maximum of 2 TrackingCategory elements.
Elements for TrackingCategory
Name Name of the tracking category (required)
OptionName Name of the option (required)
Name Name of the tracking category (required)

Creating, updating and deleting line items when updating invoices

In an update (POST) request:
  • Providing an existing LineItem with its LineItemID will update that line item.
  • Providing a LineItem with no LineItemID will create a new line item.
  • Not providing an existing LineItem with it's LineItemID will result in that line item being deleted.

Addresses on Invoices

By default, the address applied to an invoice will use the postal (POBOX) address of the Contact. However, This can be changed in Xero by applying a custom invoice template. It is not possible to manually override the address on a per-invoice basis.

Invoice Status Codes

When creating new invoices or modifying existing invoices you can optionally specify a "Status" element. New invoices can have either one of the following three status codes :

Status Description
DRAFT
  • The default status if this element is not provided with your API call
  • Can contain incomplete line items (e.g. missing account codes)
  • No journals are created so the details will not be used in any reports
SUBMITTED
  • Useful if there is an approval process required
  • No journals are created so the details will not be used in any reports
AUTHORISED
  • The "approved" state of an invoice ready for sending to a customer
  • Journals are created in Xero so all details will be used in reports
  • You can now apply payments to the invoice
  • Once an invoice is fully paid invoice the status will change to PAID
 

Invoice status changes

The following state changes are valid when updating invoices.

Existing status New status
DRAFT DRAFT
DRAFT SUBMITTED
DRAFT AUTHORISED
DRAFT DELETED
SUBMITTED SUBMITTED
SUBMITTED AUTHORISED
SUBMITTED DRAFT
SUBMITTED DELETED
AUTHORISED AUTHORISED
AUTHORISED VOIDED

When can't an invoice be updated?

An invoice can't be updated if:

  • it has been fully paid
  • it has part-payments or credit notes applied to it
  • it is in a locked period

Creating a PAID Invoice

Creating a PAID invoice is a two step process:

  • First an AUTHORISED invoice needs to be made using the Invoices endpoint.
  • Second a payment for the outstanding amount needs to be applied using the payments endpoint.

Once the invoice has been fully paid the system will move it to the PAID status.

Example of a draft sales (ACCREC) invoice with enough detail to be approved once it’s been created.

POST https://api.xero.com/api.xro/2.0/Invoices

<Invoice>
  <Type>ACCREC</Type>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </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 sales (ACCREC) invoice to ABC Limited

POST https://api.xero.com/api.xro/2.0/Invoices
<Invoice>
  <Type>ACCREC</Type>
  <Contact><ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID></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 creating a draft sales (ACCREC) invoice with a 20% discount on a line item

POST https://api.xero.com/api.xro/2.0/Invoices
<Invoice>
  <Type>ACCREC</Type>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </Contact>
  <Date>2009-08-30</Date>
  <DueDate>2009-09-20</DueDate>
  <LineAmountTypes>Exclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>Consulting services as agreed (20% off standard rate)</Description>
      <Quantity>10</Quantity>
      <UnitAmount>100.00</UnitAmount>
      <AccountCode>200</AccountCode>
      <DiscountRate>20</DiscountRate>
    </LineItem>
  </LineItems>
</Invoice>


Example of a sales (ACCREC) 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

POST https://api.xero.com/api.xro/2.0/Invoices
<Invoice>
  <Type>ACCREC</Type>
  <CurrencyCode>USD</CurrencyCode>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </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 sales (ACCREC) 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. 

POST https://api.xero.com/api.xro/2.0/Invoices
<Invoice>
  <Type>ACCREC</Type>
  <Contact>
    <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </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 a sales (ACCREC) invoice with every single element being specified:

POST https://api.xero.com/api.xro/2.0/Invoices
<Invoices>
  <Invoice>
    <Type>ACCREC</Type>
    <Contact>
      <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
    </Contact>
    <Date>2009-09-08T00:00:00</Date>
    <DueDate>2009-10-20T00:00:00</DueDate>
    <ExpectedPaymentDate>2009-10-20T00:00:00</ExpectedPaymentDate>
    <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>
        <ItemCode>Test 01<<ItemCode>
        <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>
        <ItemCode>Test 02<<ItemCode>
        <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>
      </LineItem>
    </LineItems>
  </Invoice>
</Invoices>

Deleting and Voiding Invoices

You can delete a DRAFT or SUBMITTED invoice by updating the Status to DELETED.

If an invoice has been AUTHORISED it cannot be deleted but you can set it's status to VOIDED

If you send invoices from your app you can mark them as sent in Xero by setting SentToContact as true

Example of deleting a draft invoice

POST https://api.xero.com/api.xro/2.0/Invoices/INV-239
<Invoice>
  <InvoiceNumber>INV-239</InvoiceNumber>
   <Status>DELETED</Status>
</Invoice>

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

POST https://api.xero.com/api.xro/2.0/Invoices/INV-123
<Invoice>
  <InvoiceNumber>INV-123</InvoiceNumber>
  <Status>VOIDED</Status>
</Invoice>

Example of updating an invoice to mark it as sent

POST https://api.xero.com/api.xro/2.0/Invoices/8694c9c5-7097-4449-a708-b8c1982921a4
<Invoice>
  <InvoiceID>8694c9c5-7097-4449-a708-b8c1982921a4</InvoiceID>
  <SentToContact>true</SentToContact>
</Invoice>

SummarizeErrors

If you are entering many invoices in a single API call then we recommend you utilise our response format that shows validation errors for each invoice. Each Invoice will be returned with a status element that contains the value OK or ERROR. If an invoice has a error then one or more validation errors will be returned.



Example of the altered response format using the SummarizeErrors=false parameter 

POST https://api.xero.com/api.xro/2.0/Invoices?SummarizeErrors=false

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

Uploading an Attachment

You can upload up to 10 attachments(each up to 3mb in size) per invoice, once the invoice has been created in Xero. To do this you'll need to know the ID of the invoice which you'll use to construct the URL when POST/PUTing a byte stream containing the attachment file. e.g. https://api.xero.com/api.xro/2.0/Invoices/f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/image.png. See the Attachments page for more details.

Example of uploading an attachment

POST /api.xro/2.0/Invoices/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
    Headers:
    Authorization: OAuth...
    Content Type: image/png
    Content-Length: 10293
    Body:
    {RAW-IMAGE-CONTENT}

PUT Invoices

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

Currently unsupported features

There are a number of features that are not yet supported in the API. We have documented them below with information on how you can track their status and possible interim workarounds.

Emailing Invoices

It is not possible to email an invoice through the Xero application using the Xero accounting API. To track progress on this feature request, or to add your support to it, please vote here.

Workarounds There is a solution available within the current API:
  • Download a PDF copy of the invoice
  • Retrieve the email contact details of the customer from the contacts endpoint or from the invoice endpoint
  • Send the email from your own application
  • Update the invoice, updating the <SentToContact> field to 'true', so that the fact that the invoice has been sent will be visible within Xero

Add a note to an invoice

The ability to add custom notes to an Invoice through the accounting API has not yet been supported. To track progress on this feature request, or to add your support to it, please vote here.