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

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
<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 response when retrieving a collection of expense claims

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

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
<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>

Example of updating the status of an expense claim

POST https://api.xero.com/api.xro/2.0/ExpenseClaims/e59a2c7f-1306-4078-a0f3-73537afcbba9
<ExpenseClaim>
<ExpenseClaimID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ExpenseClaimID>
<Status>AUTHORISED</Status>
</ExpenseClaim>

Example of voiding an expense claim

POST https://api.xero.com/api.xro/2.0/ExpenseClaims/e59a2c7f-1306-4078-a0f3-73537afcbba9
<ExpenseClaim>
  <ExpenseClaimID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ExpenseClaimID>
  <Status>VOIDED</Status>
</ExpenseClaim>

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
<Response>
  <ExpenseClaims>
    <ExpenseClaim status="OK">
      ...
    </ExpenseClaim>
    <ExpenseClaim status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </ExpenseClaim>
    <ExpenseClaim status="OK">
      ...
    </ExpenseClaim>
</ExpenseClaims>
</Response>