Important Update - October 2018: Last year, we announced the arrival of our new Xero Expenses product. Access to classic expense claims functionality is only available to customers who used it in the 6 months prior to 10 July 2018.
If you're planning on building a new expenses integration we suggest you create ACCPAY Invoices (bills) in Xero instead of using ExpenseClaims and Receipts. A new Xero Expenses API will be coming in 2019.
| URL | https://api.xero.com/api.xro/2.0/Receipts |
| Methods Supported | GET, PUT, POST |
| Description | Allows you to retrieve draft expense claim receipts for any user
Allows you to add or update draft expense claim receipts Allows you to attach images to draft expense claim receipts Allows you to delete draft expense claim receipts Allows you to retrieve history Allows you to add notes |
| Date | Date of receipt - YYYY-MM-DD |
| Contact | See Contacts |
| Lineitems | See LineItems. The LineItems element can contain any number of individual LineItem sub-elements. |
| User | The user in the organisation that the expense claim receipt is for. See Users |
| Reference | Additional reference number |
| LineAmountTypes | See Line Amount Types |
| SubTotal | Total of receipt excluding taxes |
| TotalTax | Total tax on receipt |
| Total | Total of receipt tax inclusive (i.e. SubTotal + TotalTax) |
| ReceiptID | Xero generated unique identifier for receipt |
| Status | Current status of receipt - see status types |
| ReceiptNumber | Xero generated sequence number for receipt in current claim for a given user |
| UpdatedDateUTC | Last modified date UTC format |
| HasAttachments | boolean to indicate if a receipt has an attachment |
| Url | URL link to a source document – shown as "Go to [appName]" in the Xero app |
| 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 |
| 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 | AccountCode must be active for the organisation. AccountCodes can only be applied to a receipt when the ShowInExpenseClaims value is true. Bank Accounts can not be applied to receipts. |
| Quantity | LineItem Quantity |
| TaxType | Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes. |
| 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. You must use the Name and Option elements instead of the TrackingCategoryID and TrackingOptionID fields. |
| DiscountRate | Percentage discount being applied to a line item. Vote here to be able to create discounts via the API. |
| ReceiptID | You can specify an individual record by appending the ReceiptID to the endpoint, i.e. GET https://.../Receipts/{identifier} |
| Modified After | The ModifiedAfter filter is actually an HTTP header: '
If-Modified-Since'.
A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only receipts 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 ) |
Example response retrieving an individual receipt
GET https://api.xero.com/api.xro/2.0/Receipts/e59a2c7f-1306-4078-a0f3-73537afcbba9
Example response retrieving a collection of receipts
GET https://api.xero.com/api.xro/2.0/Receipts
Use this method to create or update DRAFT receipts.
| The following are mandatory for a PUT / POST request | |
| Date | Date of receipt - YYYY-MM-DD |
| Contact | See Contacts |
| Lineitems | See LineItems. At least one line item is required to create a complete receipt. |
| User | The user in the organisation that the expense claim receipt is for. See Users |
| The following are optional for a PUT / POST request | |
| Reference | Additional reference number |
| LineAmountTypes | See Line Amount Types |
| SubTotal | Total of receipt excluding taxes |
| TotalTax | Total tax on receipt |
| Total | Total of receipt tax inclusive (i.e. SubTotal + TotalTax) |
| Elements for Line Items | |
| The following elements are required to submit a complete receipt | |
| 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 |
| 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 | AccountCode must be active for the organisation. AccountCodes can only be applied to a receipt when the ShowInExpenseClaims value is true. Bank Accounts can not be applied to receipts. |
| The following are optional for a PUT / POST request | |
| Quantity | LineItem Quantity |
| TaxType | Used as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes. |
| 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. You must use the Name and Option elements instead of the TrackingCategoryID and TrackingOptionID fields. |
The PUT method is similar to the POST Invoices method, however you can only create new receipts with this method.
Example of the minimum request to create a receipt
POST https://api.xero.com/api.xro/2.0/Receipts
Example request to create a receipt with all available elements
POST https://api.xero.com/api.xro/2.0/Receipts
Example request to delete a DRAFT receipt
POST https://api.xero.com/api.xro/2.0/Receipts/e59a2c7f-1306-4078-a0f3-73537afcbba9
If you are entering many receipts in a single API call then we recommend you utilise our new response format that shows validation errors for each receipt. Each Receipt will be returned with a status element that contains the value OK or ERROR. If a receipt has a error then one or more validation errors will be returned. To utilise this functionality you'll need to append ?SummarizeErrors=false to the end of your API calls.
Example of the altered response format using the SummarizeErrors=false parameter
POST https://api.xero.com/api.xro/2.0/Receipts?SummarizeErrors=false
You can upload up to 10 attachments (each up to 3mb in size) per receipt once they have been entered as drafts. To do this you'll need to know the ID of the receipt which you'll use to construct the URL when POST/PUTing a byte stream containing the image file.
Example of uploading an attachment to a receipt
POST https://api.xero.com/api.xro/2.0/Receipts/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Headers:
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293
Body:
{RAW-IMAGE-CONTENT}
View a summary of the actions made by all users to the receipt. See the History and Notes page for more details.
Example of retrieving a receipt's history
GET https://api.xero.com/api.xro/2.0/Receipts/{Guid}/History
Add a note which will appear in the history against a receipt. See the History and Notes page for more details.
Example of creating a note against a receipt
PUT https://api.xero.com/api.xro/2.0/Receipts/{Guid}/History