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

Expense Claims

Overview

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

GET https://api.xero.com/api.xro/2.0/ExpenseClaims/0b44a210-b9eb-447a-8c7b-fe5e7e40f25c

Example response when retrieving a collection of expense claims

GET https://api.xero.com/api.xro/2.0/ExpenseClaims

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.

POST https://api.xero.com/api.xro/2.0/ExpenseClaims

Example of updating the status of an expense claim

POST https://api.xero.com/api.xro/2.0/ExpenseClaims/e59a2c7f-1306-4078-a0f3-73537afcbba9

Example of voiding an expense claim

POST https://api.xero.com/api.xro/2.0/ExpenseClaims/e59a2c7f-1306-4078-a0f3-73537afcbba9

SummarizeErrors

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

POST https://api.xero.com/api.xro/2.0/ExpenseClaims?SummarizeErrors=false

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

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

Add Notes to an Expense Claim

Add a note which will apear 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

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