| 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 Email sales invoices Retrieve history for invoices and purchase bills Add notes to invoices and purchase bills |
Use this method to retrieve one or many invoices.
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) |
| 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 |
Examples response when retrieving a collection of invoices using paging
GET https://api.xero.com/api.xro/2.0/Invoices?page=1
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
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) |
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 |
|
| SUBMITTED |
|
| AUTHORISED |
|
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 |
An invoice can't be updated if:
Creating a PAID invoice is a two step process:
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
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
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
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}
You can use the API to trigger the email of a sales invoice out of Xero. The invoice must be of Type ACCREC and a valid Status for sending (SUMBITTED,AUTHORISED or PAID).
The email will be sent to the primary email address of the contact on the invoice and any additional contact persons that have IncludeInEmails flag set to true. The sender will be the user who authorised the app connection.
The subject and body of the email will generated from the organisation’s default template. You can read more about email templates
here.
There is a daily limit per Xero organisation for sending invoices. This includes emails sent via the app and the API:
An example request to trigger an email
POST https://api.xero.com/api.xro/2.0/Invoices/aa682059-c8ec-44b9-bc7f-344c94e1ffae/Email
Request Body: <Empty>
The PUT method is similar to the POST Invoices method, however you can only create new invoices with this method.
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.
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 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