Join us at Xero Developer Roadshow, June 2018 at a city near you. Register Free

Expense Claims

Important Update - May 2018: Last year, we announced the arrival of our new Xero Expenses product and very soon we'll releasing the new Xero Expenses public API. If you're planning on building an integration with Expense Claims we suggest holding off a little longer (if you can) to work out the integration path that will be best for your app. More details will be revealed over the next few weeks...


Methods Supported GET, PUT, POST
Description Allows you to submit expense claims for approval
Allows you to retrieve expense claims to see their status
Allows you to retrieve history
Allows you to add notes

GET ExpenseClaims

Use this method to retrieve either one or many expense claims.

Elements for an expense claim

User See Users
Receipts See Receipts
ExpenseClaimID Xero generated unique identifier for an expense claim
Payments See Payments
Status Current status of an expense claim - see status types
UpdatedDateUTC Last modified date UTC format
Total The total of an expense claim being paid
AmountDue The amount due to be paid for an expense claim
AmountPaid The amount still to pay for an expense claim
PaymentDueDate The date when the expense claim is due to be paid YYYY-MM-DD
ReportingDate The date the expense claim will be reported in Xero YYYY-MM-DD

Optional parameters

ExpenseClaimID You can specify an individual record by appending the ExpenseClaimID to the endpoint, i.e. GET https://.../ExpenseClaims/{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 for retrieving an individual ExpenseClaim


Example response when retrieving a collection of expense claims


POST ExpenseClaims

Use this method to submit one or many expense claims.

Note that you cannot pay an expense claim via the Xero API. Payment needs to be done in the Xero app.

Elements for creating/updating expense claims

The following are mandatory for a PUT / POST request
User See Users
Receipts See Receipts
The following are optional for a POST request
Status Current status of an expense claim - see status types
The Receipts element can contain one or more Receipt sub-elements. At least one valid receipt element is required to create an expense claim.
The following elements are required to submit a complete receipt
ReceiptID The Xero identifier for the Receipt e.g. e59a2c7f-1306-4078-a0f3-73537afcbba9

PUT ExpenseClaims

The PUT method is similar to the POST ExpenseClaims method however you can only create expense claims with this method.

Example of minimum elements required to submit an expense claim for a user with two receipts.


Example of updating the status of an expense claim


Example of voiding an expense claim



If you are entering many expense claims in a single API call then we recommend you utilise our new response format that shows validation errors for each receipt. The new response messages for validating bulk API calls would mean a breaking change so to utilise this functionality you'll need to append ?SummarizeErrors=false to the end of your API calls.

Note that each ExpenseClaim is now returned with a status element which will either contain the value OK or ERROR. If a receipt has a error then one or more validation errors will be returned.

Example of the SummarizeErrors response format


Retrieving History

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

Example of retrieving a expense claim's history


Add Notes to an Expense Claim

Add a note which will appear in the history against an expense claim. See the History and Notes page for more details.

Example of creating a note against a expense claim