Items

Try in API Previewer

Overview

URL https://api.xero.com/api.xro/2.0/Items
Methods Supported GET, PUT, POST
Description Allows you to retrieve any items
Allows you to add or update items for use on invoices and credit notes

Elements for Items

The following are mandatory for a PUT / POST request
<Code> User defined item code
The following are recommended for a PUT / POST request
<Description> Description of item
<PurchaseDetails> See Purchases & Sales
<SalesDetails> See Purchases & Sales

Elements for Purchases and Sales

The <PurchaseDetails> and <SalesDetails> elements can contain a number of individual sub-elements.

The following are recommended for a PUT / POST request
<UnitPrice> Unit Price of item
<AccountCode> Account code to be used for purchased item
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.

POST Items

Use this method to create or update an item.

Example – Minimum elements

Minimum elements required to add a new item to ABC Limited with no sale or purchase price or description.

<Item>
  <Code>Item-1</Code>
 </Item>

Example – AR invoice line item to be approved.

Item with enough detail to populate an invoice line item so that an Accounts Receivable invoice can be approved.

<Item>
  <Code>Merino-2011-LG</Code>
  <Description>2011 Merino Wool Sweater - Large</Description>
  <SalesDetails>
    <UnitPrice>299.00</UnitPrice>
    <AccountCode>200</AccountCode>
  </SalesDetails>
</Item>

Example – AP invoice line item to be approved.

Item with enough detail to populate an invoice line item so that an Accounts Payable invoice can be approved.
This example also overides the default tax treatment for the account code and uses NONE.

<Item>
  <Code>SilkScarf-2011-RED</Code>
  <Description>2011 Silk Scarf - RED</Description>
  <PurchaseDetails>
    <UnitPrice>42.00</UnitPrice>
    <AccountCode>300</AccountCode>
    <TaxType>NONE</TaxType>
  </PurchaseDetails>
</Item>

Example – details for both invoice types

Example of a typical item with purchase and sales details so that it can be used on both Accounts Payable and Accounts Receivable invoices. 

<Item>
  <Code>Merino-2011-LG</Code>
  <Description>2011 Merino Sweater - LARGE</Description>
  <PurchaseDetails>
    <UnitPrice>149.00</UnitPrice>
    <AccountCode>300</AccountCode>
  </PurchaseDetails>
  <SalesDetails>
    <UnitPrice>299.00</UnitPrice>
    <AccountCode>200</AccountCode>
  </SalesDetails>
</Item>

PUT Item

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

GET Items

Use this method to retrieve either one or many items.

Optional parameters

Record filter You can specify an individual record by appending the value to the endpoint, i.e.
GET https://…/Items/{identifier}
ItemID – The Xero identifier for an Item
e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
Code – The Code e.g. ITEM-001
Modified After The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘.
A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only items 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)

Examples for GET Items

Example 1. This is an example response when a filter has been applied to request just a single item. In this case the Item with the identifier(Code) of Merino-2011-LG was specified. The UnitPrice element for Purchases and Sales is always returned on a GET Request. AccountCode and TaxType are returned if they have been set

<Item>
  <ItemID>9a59ea90-942e-484d-9b71-d00ab607e03b</ItemID>
  <Code>Merino-2011-LG</Code>
  <Description>2011 Merino Sweater - LARGE</Description>
  <PurchaseDetails>
    <UnitPrice>149.00</UnitPrice>
    <AccountCode>300</AccountCode>
  </PurchaseDetails>
  <SalesDetails>
    <UnitPrice>299.00</UnitPrice>
    <AccountCode>200</AccountCode>
  </SalesDetails>
</Item>

Example of Items’ usage inside Invoices endpoint with its override properties.