Receipts (Deprecated)

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.

Overview

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

GET Receipts

Use this method to retrieve either one or many draft receipts.

Elements for Receipts

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.

Optional parameters

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

POST Receipts

Use this method to create or update DRAFT receipts.

Elements for 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.

PUT Receipts

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

Submitting and entering many receipts

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

Uploading a receipt image

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}

Retrieving History

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 Notes to a Receipt

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