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

GET Receipts

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

Elements for Receipts

DateDate of receipt - YYYY-MM-DD
ContactSee Contacts
LineitemsSee LineItems. The LineItems element can contain any number of individual LineItem sub-elements.
UserThe user in the organisation that the expense claim receipt is for. See Users
ReferenceAdditional reference number
LineAmountTypesSee Line Amount Types
SubTotalTotal of receipt excluding taxes
TotalTaxTotal tax on receipt
TotalTotal of receipt tax inclusive (i.e. SubTotal + TotalTax)
ReceiptIDXero generated unique identifier for receipt
StatusCurrent status of receipt - see status types
ReceiptNumberXero generated sequence number for receipt in current claim for a given user
UpdatedDateUTCLast modified date UTC format
HasAttachmentsboolean to indicate if a receipt has an attachment
UrlURL link to a source document – shown as "Go to [appName]" in the Xero app
Elements for Line Items
DescriptionDescription 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
UnitAmountLineitem 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.
AccountCodeAccountCode 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.
QuantityLineItem Quantity
TaxTypeUsed as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes.
LineAmountIf you wish to omit either of the Quantity or UnitAmount you can provide a LineAmount and Xero will calculate the missing amount for you
TrackingOptional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements. You must use the Name and Option elements instead of the TrackingCategoryID and TrackingOptionID fields.
DiscountRatePercentage discount being applied to a line item. Vote here to be able to create discounts via the API.

Optional parameters

ReceiptID You can specify an individual record by appending the ReceiptID to the endpoint, i.e.GET https://.../Receipts/{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 retrieving an individual receipt

GET https://api.xero.com/api.xro/2.0/Receipts/e59a2c7f-1306-4078-a0f3-73537afcbba9
<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 response retrieving a collection of receipts

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

POST Receipts

Use this method to create or update DRAFT receipts.

Elements for Receipts

The following are mandatory for a PUT / POST request
DateDate of receipt - YYYY-MM-DD
ContactSee Contacts
LineitemsSee LineItems. At least one line item is required to create a complete receipt.
UserThe user in the organisation that the expense claim receipt is for. See Users
The following are optional for a PUT / POST request
ReferenceAdditional reference number
LineAmountTypesSee Line Amount Types
SubTotalTotal of receipt excluding taxes
TotalTaxTotal tax on receipt
TotalTotal of receipt tax inclusive (i.e. SubTotal + TotalTax)
Elements for Line Items
The following elements are required to submit a complete receipt
DescriptionDescription 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
UnitAmountLineitem 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.
AccountCodeAccountCode 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 optional for a PUT / POST request
QuantityLineItem Quantity
TaxTypeUsed as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes.
LineAmountIf you wish to omit either of the Quantity or UnitAmount you can provide a LineAmount and Xero will calculate the missing amount for you
TrackingOptional Tracking Category - see Tracking. Any LineItem can have a maximum of 2 TrackingCategory elements. You must use the Name and Option elements instead of the TrackingCategoryID and TrackingOptionID fields.

PUT Receipts

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

Example of the minimum request to create a receipt

POST https://api.xero.com/api.xro/2.0/Receipts
<Receipt>
  <Date>2011-09-30</Date>
  <User>
    <UserID>0ccf3aa2-3207-422f-82ef-2e3fc1ad5a82</UserID>
  </User>
  <Contact>
      <ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
  </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>
</Receipt>

Example request to create a receipt with all available elements

POST https://api.xero.com/api.xro/2.0/Receipts
<Receipt>
  <User>
    <UserID>0ccf3aa2-3207-422f-82ef-2e3fc1ad5a82</UserID>
  </User>
  <Contact>
    <Name>Joe's Coffee House</Name>
  </Contact>
  <Date>2016-09-20T00:00:00</Date>
  <LineAmountTypes>Inclusive</LineAmountTypes>
  <LineItems>
    <LineItem>
      <Description>thing</Description>
      <UnitAmount>5.00</UnitAmount>
      <TaxType>INPUT</TaxType>
      <TaxAmount>.45</TaxAmount>
      <LineAmount>5.00</LineAmount>
      <AccountCode>400</AccountCode>
      <Tracking>
        <TrackingCategory>
          <Name>Region</Name>
          <Option>North</Option>
        </TrackingCategory>
      </Tracking>
      <Quantity>1.0000</Quantity>
    </LineItem>
  </LineItems>
</Receipt>

Example request to delete a DRAFT receipt

POST https://api.xero.com/api.xro/2.0/Receipts/e59a2c7f-1306-4078-a0f3-73537afcbba9
<Receipt>
  <ReceiptID>e59a2c7f-1306-4078-a0f3-73537afcbba9</ReceiptID>
  <Status>DELETED</Status>
  <User>
     <UserID>c81045b2-5740-4aea-bf8a-3956941af387</UserID>
  </User>
</Receipt>

Submitting and entering many receipts

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. Each Receipt will be returned with a status element that contains the value OK or ERROR. If a receipt has a error then one or more validation errors will be returned. To utilise this functionality you'll need to append ?SummarizeErrors=false to the end of your API calls.

Example of the altered response format using the SummarizeErrors=false parameter

POST https://api.xero.com/api.xro/2.0/Receipts?SummarizeErrors=false 
<Response>
  <Receipts>
    <Receipt status="OK">
      ...
    </Receipt>
    <Receipt status="ERROR">
      <ValidationErrors>
          <ValidationError>
              <Message>....</Message>
          </ValidationError>
          .....
     </ValidationErrors>
    </Receipt>
    <Receipt status="OK">
      ...
    </Receipt>
</Receipts>
</Response>

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.

Example of uploading an attachment to a receipt

POST https://api.xero.com/api.xro/2.0/Receipts/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Headers:
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293
Body:
{RAW-IMAGE-CONTENT}