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

Elements for an expense claim

The following are mandatory for a PUT / POST request
<User> See Users
<Receipts> See Receipts
The following are only returned on a GET request
<ExpenseClaimID> Xero generated unique identifier for an expense claim
<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
<ReportingDate> The date the expense claim will be reported in Xero

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

POST ExpenseClaims

Use this method to submit one or many expense claims.

Note that you cannot authorise or pay and expense claim via the Xero API at this time. Authorisation and payment needs to be done in the Xero app.

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

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 0b44a210-b9eb-447a-8c7b-fe5e7e40f25c 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>0b44a210-b9eb-447a-8c7b-fe5e7e40f25c</ExpenseClaimID>
      <Status>PAID</Status>
      <UpdatedDateUTC>2011-10-06T18:23:24.363</UpdatedDateUTC>
      <User>
        <UserID>d6362594-ffec-4435-abe8-469941ff1501</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
        <UpdatedDateUTC>2011-08-28T22:10:07.063</UpdatedDateUTC>
        <IsSubscriber>false</IsSubscriber>
        <OrganisationRole>FINANCIALADVISER</OrganisationRole>
      </User>
      <Receipts>
        <Receipt>
          <ReceiptID>4dfefee8-15c3-4c30-ba0a-cb78d96d709a</ReceiptID>
          <ReceiptNumber>2</ReceiptNumber>
          <Status>AUTHORISED</Status>
          <User>
            <UserID>d6362594-ffec-4435-abe8-469941ff1501</UserID>
            <FirstName>Joe</FirstName>
            <LastName>Bloggs</LastName>
            <UpdatedDateUTC>2011-08-28T22:10:07.063</UpdatedDateUTC>
            <IsSubscriber>false</IsSubscriber>
            <OrganisationRole>FINANCIALADVISER</OrganisationRole>
          </User>
          <Contact>
            <ContactID>827deebb-d4dd-4b52-933f-851631ab93c4</ContactID>
            <Name>Coco Cafe</Name>
          </Contact>
          <Date>2013-10-11T00:00:00</Date>
          <UpdatedDateUTC>2011-10-06T00:03:06.18</UpdatedDateUTC>
          <Reference>MRE 08</Reference>
          <LineAmountTypes>Inclusive</LineAmountTypes>
          <LineItems>
            <LineItem>
              <Description>Breakfast before MRE conference</Description>
              <UnitAmount>16.90</UnitAmount>
              <TaxType>NONE</TaxType>
              <TaxAmount>0.00</TaxAmount>
              <LineAmount>16.90</LineAmount>
              <AccountCode>684</AccountCode>
              <Quantity>1.0000</Quantity>
            </LineItem>
          </LineItems>
          <SubTotal>16.90</SubTotal>
          <TotalTax>0.00</TotalTax>
          <Total>16.90</Total>
          <HasAttachments>false</HasAttachments>
        </Receipt>
        <Receipt>
          <ReceiptID>5c578500-d093-4a29-9dc4-ff6c9c74b72d</ReceiptID>
          <ReceiptNumber>1</ReceiptNumber>
          <Status>AUTHORISED</Status>
          <User>
            <UserID>d6362594-ffec-4435-abe8-469941ff1501</UserID>
            <FirstName>Joe</FirstName>
            <LastName>Bloggs</LastName>
            <UpdatedDateUTC>2011-08-28T22:10:07.063</UpdatedDateUTC>
            <IsSubscriber>false</IsSubscriber>
            <OrganisationRole>FINANCIALADVISER</OrganisationRole>
          </User>
          <Contact>
            <ContactID>b89da77c-1a13-4893-8d65-71cd38fc623a</ContactID>
            <Name>Fulton Airport Parking</Name>
          </Contact>
          <Date>2013-10-11T00:00:00</Date>
          <UpdatedDateUTC>2011-10-06T00:03:06.18</UpdatedDateUTC>
          <Reference>MRE 08</Reference>
          <LineAmountTypes>Inclusive</LineAmountTypes>
          <LineItems>
            <LineItem>
              <Description>Parking for MRE conference</Description>
              <UnitAmount>18.00</UnitAmount>
              <TaxType>NONE</TaxType>
              <TaxAmount>0.00</TaxAmount>
              <LineAmount>18.00</LineAmount>
              <AccountCode>684</AccountCode>
              <Quantity>1.0000</Quantity>
            </LineItem>
          </LineItems>
          <SubTotal>18.00</SubTotal>
          <TotalTax>0.00</TotalTax>
          <Total>18.00</Total>
          <HasAttachments>false</HasAttachments>
        </Receipt>
      </Receipts>
      <Payments>
        <Payment>
          <Date>2013-10-18T00:00:00</Date>
          <Amount>34.90</Amount>
          <Reference>FP101897</Reference>
          <Account>
            <AccountID>ceef66a5-a545-413b-9312-78a53caadbc4</AccountID>
            <Code>090</Code>
            <Name>Checking Account</Name>
          </Account>
        </Payment>
      </Payments>
      <Total>34.90</Total>
      <AmountDue>0.00</AmountDue>
      <AmountPaid>34.90</AmountPaid>
      <PaymentDueDate>2013-10-18T00:00:00</PaymentDueDate>
      <ReportingDate>2013-10-18T00:00:00</ReportingDate>
    </ExpenseClaim>

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>0b44a210-b9eb-447a-8c7b-fe5e7e40f25c</ExpenseClaimID>
      <Status>PAID</Status>
      <UpdatedDateUTC>2011-10-06T18:23:24.363</UpdatedDateUTC>
      <User>
        <UserID>d6362594-ffec-4435-abe8-469941ff1501</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
        <UpdatedDateUTC>2011-08-28T22:10:07.063</UpdatedDateUTC>
        <IsSubscriber>false</IsSubscriber>
        <OrganisationRole>FINANCIALADVISER</OrganisationRole>
      </User>
      <Total>34.90</Total>
      <AmountDue>0.00</AmountDue>
      <AmountPaid>34.90</AmountPaid>
      <PaymentDueDate>2013-10-18T00:00:00</PaymentDueDate>
      <ReportingDate>2013-10-18T00:00:00</ReportingDate>
    </ExpenseClaim>
    <ExpenseClaim>
      <ExpenseClaimID>fb0372d7-4d35-4b99-89e1-8dc0fff13cae</ExpenseClaimID>
      <Status>PAID</Status>
      <UpdatedDateUTC>2011-10-06T18:27:11.907</UpdatedDateUTC>
      <User>
        <UserID>d6362594-ffec-4435-abe8-469941ff1501</UserID>
        <FirstName>Joe</FirstName>
        <LastName>Bloggs</LastName>
        <UpdatedDateUTC>2011-08-28T22:10:07.063</UpdatedDateUTC>
        <IsSubscriber>false</IsSubscriber>
        <OrganisationRole>FINANCIALADVISER</OrganisationRole>
      </User>
      <Total>29.50</Total>
      <AmountDue>0.00</AmountDue>
      <AmountPaid>29.50</AmountPaid>
      <PaymentDueDate>2013-12-03T00:00:00</PaymentDueDate>
      <ReportingDate>2013-12-03T00:00:00</ReportingDate>
    </ExpenseClaim>
  </ExpenseClaims>