Skip to content
 

Developer

See all pages
Try Xero Free

Expense Claims

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

Elements for Receipts

The following are mandatory for a PUT / POST request
<User> See Users
<Receipts> See Receipts

Elements for Receipts
The <Receipts> element can contain one or more <Receipt> sub-elements. At least one valid receipt element is required to create an expense claim.

POST ExpenseClaims

Use this method to submit one or many expense claims

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

<ExpenseClaims>
    <ExpenseClaim>
      <User>
        <UserID>7cf47fe2-c3dd-4c6b-9895-7ba767ba529c</UserID>
      </User>
      <Receipts>
        <Receipt>
          <ReceiptID>06f6fd50-97e6-40ac-94b0-d5215d836905</ReceiptID>
        </Receipt>
        <Receipt>
          <ReceiptID>5b7ddbb1-a0cf-4c3b-860d-a4521f3f4599</ReceiptID>
        </Receipt>
      </Receipts>
    </ExpenseClaim>
</ExpenseClaims>

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 e.g. POST /api.xro/2.0/ExpenseClaims?SummarizeErrors=false

Below is an example of the altered response format. 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. 

<Response>
  <ExpenseClaims>
    <ExpenseClaim status="OK">
      ...
    </ExpenseClaim>
    <ExpenseClaim status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </ExpenseClaim>
    <ExpenseClaim status="OK">
      ...
    </ExpenseClaim>
</ExpenseClaims>
</Response>

Example of voiding an expense claim

<ExpenseClaim>
  <ExpenseClaimID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ExpenseClaimID>
  <Status>VOIDED</Status>
</ExpenseClaim>

PUT ExpenseClaims

The PUT method is similar to the POST ExpenseClaims method.

GET ExpenseClaims

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

Optional parameters

The following elements are required to submit a complete receipt
<ReceiptID> The Xero identifier for the Receipt e.g. e59a2c7f-1306-4078-a0f3-73537afcbba9
Record filter You can specify an individual record by appending the value to the endpoint, i.e.
GET https://…/ExpenseClaims/{identifier}
ExpenseClaimID – The Xero identifier for an Expense Claim
e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
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)

By default GET ExpenseClaims responses are formatted as XML. You can also retrieve responses in JSON format.

Examples for GET ExpenseClaims

Example 1. This is an example response when a filter has been applied to request just a single expense claim. In this case the Expense Claim ID of e59a2c7f-1306-4078-a0f3-73537afcbba9 was specified. NB The response format is more detailed compared with when multiple expense claims are returned. This response includes full contact details and line items.

<ExpenseClaim>
<ExpenseClaimID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ExpenseClaimID>
      <Status>AUTHORISED</Status>
      <CreatedDateUTC>2011-09-23T03:06:58.61</CreatedDateUTC>
      <UpdatedDateUTC>2011-09-23T03:16:56.67</UpdatedDateUTC>
      <User>
        <UserID>7cf47fe2-c3dd-4c6b-9895-7ba767ba529c</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
      </User>
      <Receipts>
        <Receipt>
          <ReceiptID>0d9cfee4-a3df-4a36-bc45-8388ae5bc3b7</ReceiptID>
          <Status>AUTHORISED</Status>
          <User>
            <UserID>7cf47fe2-c3dd-4c6b-9895-7ba767ba529c</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
          </User>
          <Contact>
            <ContactID>7f71b205-4ad9-4779-8479-60f46e91fa5c</ContactID>
            <Name>Mojo Coffee</Name>
          </Contact>
          <Date>2011-09-23T00:00:00</Date>
          <UpdatedDateUTC>2011-09-23T03:03:42.26</UpdatedDateUTC>
          <LineAmountTypes>Inclusive</LineAmountTypes>
          <LineItems>
            <LineItem>
              <Description>Lunch</Description>
              <UnitAmount>12.80</UnitAmount>
              <TaxType>INPUT2</TaxType>
              <TaxAmount>1.67</TaxAmount>
              <LineAmount>12.80</LineAmount>
              <Quantity>1.0000</Quantity>
            </LineItem>
          </LineItems>
          <SubTotal>11.13</SubTotal>
          <TotalTax>1.67</TotalTax>
          <Total>12.80</Total>
          <HasAttachments>false</HasAttachments>
        </Receipt>
        <Receipt>
          <ReceiptID>443518d1-4f00-4ae3-9668-ce28c66a64ac</ReceiptID>
          <Status>AUTHORISED</Status>
          <User>
            <UserID>7cf47fe2-c3dd-4c6b-9895-7ba767ba529c</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
          </User>
          <Contact>
            <ContactID>7f71b205-4ad9-4779-8479-60f46e91fa5c</ContactID>
            <Name>Mojo Coffee</Name>
          </Contact>
          <Date>2010-07-15T00:00:00</Date>
          <UpdatedDateUTC>2011-09-23T02:54:42.26</UpdatedDateUTC>
          <LineAmountTypes>Inclusive</LineAmountTypes>
          <LineItems>
            <LineItem>
              <Description>Coffee with client to discuss support contract</Description>
              <UnitAmount>3.80</UnitAmount>
              <TaxType>INPUT2</TaxType>
              <TaxAmount>0.50</TaxAmount>
              <LineAmount>3.80</LineAmount>
              <Quantity>1.0000</Quantity>
            </LineItem>
          </LineItems>
          <SubTotal>3.30</SubTotal>
          <TotalTax>0.50</TotalTax>
          <Total>3.80</Total>
          <HasAttachments>false</HasAttachments>
        </Receipt>
      </Receipts>
      <Total>16.60</Total>
    </ExpenseClaim>
  </ExpenseClaims>

Example 2. Notice the subtle differences from the example above. As many expense claims are being returned only a summary of the contact is returned and no line details are returned – this is to keep the response more compact. 

<ExpenseClaims>
    <ExpenseClaim>
      <ExpenseClaimID>42a7abb9-5d71-4985-a865-9db6980439ea</ExpenseClaimID>
      <Status>AUTHORISED</Status>
      <CreatedDateUTC>2011-09-23T03:06:58.61</CreatedDateUTC>
      <UpdatedDateUTC>2011-09-23T03:16:56.67</UpdatedDateUTC>
      <User>
        <UserID>7cf47fe2-c3dd-4c6b-9895-7ba767ba529c</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
      </User>
      <Total>16.60</Total>
    </ExpenseClaim>
    <ExpenseClaim>
      <ExpenseClaimID>4aa07e20-dbee-4ca9-b040-bf3d2ad02b14</ExpenseClaimID>
      <Status>SUBMITTED</Status>
      <CreatedDateUTC>2011-09-26T21:19:58.097</CreatedDateUTC>
      <UpdatedDateUTC>2011-09-26T21:19:58.19</UpdatedDateUTC>
      <User>
        <UserID>7cf47fe2-c3dd-4c6b-9895-7ba767ba529c</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
      </User>
      <Total>3.80</Total>
    </ExpenseClaim>