Receipts


Overview

URL https://api.xero.com/api.xro/2.0/Receipts
Methods Supported GET, PUT, POST
Description Allows you to retrieve draft expense claim receipts for any user
Allows you to add or update draft expense claim receipts
Allows you to attach images to draft expense claim receipts
Allows you to delete draft expense claim receipts

Elements for Receipts

The following are mandatory for a PUT / POST request
<Date> Date of receipt – YYYY-MM-DD
<Contact> See Contacts
<Lineitems> See LineItems
<User> The user in the organisation that the expense claim receipt is for. See Users
The following are optional for a PUT / POST request
<Reference> Additional reference number
<LineAmountTypes> See Line Amount Types
<SubTotal> Total of receipt excluding taxes
<TotalTax> Total tax on receipt
<Total> Total of receipt tax inclusive (i.e. SubTotal + TotalTax)
The following are only returned on a GET request
<ReceiptID> Xero generated unique identifier for receipt
<Status> Current status of receipt – see status types
<ReceiptNumber> Xero generated sequence number for receipt in current claim for a given user
<UpdatedDateUTC> Last modified date UTC format
<HasAttachments> boolean to indicate if a receipt has an attachment
<Url> URL link to a source document – shown as “Go to [appName]” in the Xero app

Elements for Line Items


The <LineItems> element can contain any number of individual <LineItem> sub-elements. At least one line item is required to create a complete receipt.

All of these elements are returned on a GET request.
The following elements are required to submit a complete receipt
<Description> Description needs to be at least 1 char long. A line item with just a description (i.e no unit amount or quantity) can be created by specifying just a <Description> element that contains at least 1 character
<UnitAmount> Lineitem unit amount. By default, unit amount will be rounded to two decimal places. You can opt in to use four decimal places by adding the querystring parameter unitdp=4 to your query. See the Rounding in Xero guide for more information.
<AccountCode> AccountCode must be active for the organisation. AccountCodes can only be applied to a receipt when the ShowInExpenseClaims value is true. Bank Accounts can not be applied to receipts.
The following are recommended for a PUT / POST request
<Quantity> LineItem Quantity
The following are optional for a PUT / POST request
<TaxType> Used as an override if the default Tax Code for the selected <AccountCode> is not correct – see TaxTypes.
<LineAmount> If you wish to omit either of the <Quantity> or <UnitAmount> you can provide a LineAmount and Xero will calculate the missing amount for you
<Tracking> Optional Tracking Category – see Tracking. Any LineItem can have a maximum of 2 <TrackingCategory> elements.
The following elements may be returned on a GET request
<DiscountRate> Percentage discount being applied to a line item. Vote here to be able to create discounts via the API.

POST Receipts

Use this method to create or update a DRAFT receipt.

Example – draft minimum elements

Example of minimum elements required to add a new draft receipt from City Coffeworks with one line item

<Receipt>
        <Date>2011-09-30</Date>
        <Contact>
            <Name>City Coffeeworks</Name>
        </Contact>
        <LineAmountTypes>Inclusive</LineAmountTypes>
        <LineItems>
        <LineItem>
            <Description>Coffee with client to discuss support contract</Description>
            <UnitAmount>13.80</UnitAmount>
            <AccountCode>420</AccountCode>
        </LineItem>
        </LineItems>
        <Total>13.80</Total>
        <User>
            <UserID>c81045b2-5740-4aea-bf8a-3956941af387</UserID>
        </User>
</Receipt>

Uploading a receipt image

You can upload up to 10 attachments(each up to 3mb in size) per receipt once they have been entered as drafts. To do this you’ll need to know the ID of the receipt which you’ll use to construct the URL when POST/PUTing a byte stream containing the image file. e.g. https://api.xero.com/api.xro/2.0/Receipts/f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/image.png.

e.g.

POST /api.xro/2.0/Receipts/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293

{RAW-IMAGE-CONTENT}

Submitting and entering many receipts

You can submit an expense claim consisting of one or many draft receipts using the Expense Claims endpoint.

If you are entering many receipts 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/Receipts?SummarizeErrors=false

Example – altered response

Below is an example of the altered response format. Note that each Receipt 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>
  <Receipts>
    <Receipt status="OK">
      ...
    </Receipt>
    <Receipt status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </Receipt>
    <Receipt status="OK">
      ...
    </Receipt>
</Receipts>
</Response>

Example – delete draft

Example of deleting a draft receipt.

<Receipt>
  <ReceiptID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ReceiptID>
  <Status>DELETED</Status>
  <User>
     <UserID>c81045b2-5740-4aea-bf8a-3956941af387</UserID>
  </User>
</Receipt>

PUT Receipts

The PUT method is similar to the POST Invoices method, however you can only create new receipts with this method.


GET Receipts

Use this method to retrieve either one or many draft receipts.

Optional parameters

Record filter You can specify an individual record by appending the value to the endpoint, i.e.
GET https://…/Receipts/{identifier}
ReceiptID – The Xero identifier for an Receipt
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 Receipts responses are formatted as XML. You can also retrieve responses in JSON format.

Example – individual receipt

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

<Receipts>
    <Receipt>
      <ReceiptID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ReceiptID>
      <ReceiptNumber>6</ReceiptNumber>
      <Status>DRAFT</Status>
      <User>
        <UserID>c81045b2-5740-4aea-bf8a-3956941af387</UserID>
        <FirstName>John</FirstName>
        <LastName>Smith</LastName>
      </User>
      <Contact>
        <ContactID>ee9619df-7419-446d-af3d-6becf72d9e64</ContactID>
        <ContactStatus>ACTIVE</ContactStatus>
        <Name>Faster Taxis</Name>
        <Addresses>
          <Address>
            <AddressType>POBOX</AddressType>
          </Address>
          <Address>
            <AddressType>STREET</AddressType>
          </Address>
        </Addresses>
        <Phones>
          <Phone>
            <PhoneType>MOBILE</PhoneType>
          </Phone>
          <Phone>
            <PhoneType>FAX</PhoneType>
          </Phone>
          <Phone>
            <PhoneType>DDI</PhoneType>
          </Phone>
          <Phone>
            <PhoneType>DEFAULT</PhoneType>
          </Phone>
        </Phones>
        <UpdatedDateUTC>2011-10-02T19:41:43.817</UpdatedDateUTC>
      </Contact>
      <Date>2011-09-30T00:00:00</Date>
      <UpdatedDateUTC>2011-10-02T20:09:09.067</UpdatedDateUTC>
      <LineAmountTypes>Inclusive</LineAmountTypes>
      <LineItems>
        <LineItem>
          <Description>Cab to Airport</Description>
          <UnitAmount>18.62</UnitAmount>
          <TaxType>INPUT2</TaxType>
          <TaxAmount>2.43</TaxAmount>
          <LineAmount>18.62</LineAmount>
          <AccountCode>420</AccountCode>
          <Quantity>1.0000</Quantity>
        </LineItem>
      </LineItems>
      <SubTotal>16.19</SubTotal>
      <TotalTax>2.43</TotalTax>
      <Total>18.62</Total>
      <HasAttachments>false</HasAttachments>
    </Receipt>
  </Receipts>

Example – many receipts

Notice the subtle differences from the example above. As many receipts 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.

<Receipts>
    <Receipt>
      <ReceiptID>b7072163-84e5-4501-a7bd-2849927980c0</ReceiptID>
      <ReceiptNumber>1</ReceiptNumber>
      <User>
        <UserID>c81045b2-5740-4aea-bf8a-3956941af387</UserID>
        <FirstName>John</FirstName>
        <LastName>Smith</LastName>
      </User>
      <Contact>
        <ContactID>7f71b205-4ad9-4779-8479-60f46e91fa5c</ContactID>
        <Name>City Coffeeworks</Name>
      </Contact>
      <Date>2010-07-15T00:00:00</Date>
      <UpdatedDateUTC>2011-10-02T19:08:18.767</UpdatedDateUTC>
      <LineAmountTypes>Inclusive</LineAmountTypes>
      <SubTotal>3.30</SubTotal>
      <TotalTax>0.50</TotalTax>
      <Total>3.80</Total>
      <HasAttachments>false</HasAttachments>
    </Receipt>
    
    <Receipt>
      <ReceiptID>78f5131c-e5a2-4070-89f7-c77a18bb46df</ReceiptID>
      <ReceiptNumber>2</ReceiptNumber>
      
      ....
    </Receipt>
</Receipts>