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 Retrieve history Add notes

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
CISDeduction	CISDeduction withheld by the contractor to be paid to HMRC on behalf of subcontractor (Available for organisations under UK Construction Industry Scheme)
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

Examples response when retrieving a collection of invoices without paging

GET https://api.xero.com/api.xro/2.0/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.
createdByMyApp	When set to true you'll only retrieve Invoices created by your app
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

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

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)

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 :

 

Invoice status changes

The following state changes are valid when updating invoices.

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

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

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

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

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

Example of a sales (ACCREC) invoice with every single element being specified:

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

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

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

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

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.

Webhooks

You can create a subscription to get invoice events. Create and update events are available (incuding when invoices are archived). See the Webhooks page for more details.

Retrieving History

View a summary of the actions made by all users to the invoice. See the History and Notes page for more details.

Example of retrieving a invoice's history

GET https://api.xero.com/api.xro/2.0/Invoices/{Guid}/History

Add Notes to a Invoice

Add a note which will apear in the history against a invoice. See the History and Notes page for more details.

Example of creating a note against a invoice

PUT https://api.xero.com/api.xro/2.0/Invoices/{Guid}/History