Items


Overview

URL https://api.xero.com/api.xro/2.0/Items
Methods Supported GET, PUT, POST, DELETE
Description Allows you to retrieve any items
Allows you to add or update tracked items
Allows you to add or update untracked items
Allows you to delete items

Tracked vs Untracked Items

If an item is tracked it means Xero tracks the quantity on hand and value of the item. There are stricter business rules around tracked items to facilitate this e.g. you can’t create a sales invoice for that item if you don’t have sufficient quantity on hand.

Untracked items are goods or services you can specify on transactions but Xero does not track quantities on hand or total value.

Read more about tracked and untracked items in Xero’s help centre.

Elements for Items

The following is required for a PUT / POST
<Code> User defined item code (max length = 30)
The following is required for a PUT / POST on a tracked inventory item
<InventoryAssetAccountCode> The inventory asset account for the item. The account must be of type INVENTORY. The COGSAccountCode in PurchaseDetails is also required to create a tracked item
The following are optional for a PUT / POST
<Name> The name of the item (max length = 50)
<IsSold> Boolean value, defaults to true. When IsSold is true the item will be available on sales transactions in the Xero UI. If IsSold is updated to false then Description and SalesDetails values will be nulled.
<IsPurchased> Boolean value, defaults to true. When IsPurchased is true the item is available for purchase transactions in the Xero UI. If IsPurchased is updated to false then PurchaseDescription and PurchaseDetails values will be nulled.
<Description> The sales description of the item (max length = 4000)
<PurchaseDescription> The purchase description of the item (max length = 4000)
<PurchaseDetails> See Purchases & Sales
<SalesDetails> See Purchases & Sales
The following are read-only
<IsTrackedAsInventory> True for items that are tracked as inventory. An item will be tracked as inventory if the InventoryAssetAccountCode and COGSAccountCode are set.
<TotalCostPool> The value of the item on hand. Calculated using average cost accounting.
<QuantityOnHand> The quantity of the item on hand
<UpdatedDateUTC> Last modified date in UTC format

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 the item. By default UnitPrice is rounded to two decimal places. You can use 4 decimal places by adding the unitdp=4 querystring parameter to your request.
<AccountCode> Default account code to be used for purchased/sale. Not applicable to the purchase details of tracked items
<COGSAccountCode> Cost of goods sold account. Only applicable to the purchase details of tracked items.
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 items.

Example – Minimum elements

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

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

Example – An untracked item with sales and purchase details

Example of a typical untracked 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>
  <Name>Full Tracked Item</Name>
  <Description>2011 Merino Sweater - LARGE</Description>
  <PurchaseDescription>2011 Merino Sweater - LARGE</PurchaseDescription>
  <PurchaseDetails>
    <UnitPrice>149.0000</UnitPrice>
    <AccountCode>300</AccountCode>
  </PurchaseDetails>
  <SalesDetails>
    <UnitPrice>299.0000</UnitPrice>
    <AccountCode>200</AccountCode>
  </SalesDetails>
</Item>

Example – minimum to create a tracked item

This example shows the minimum values required to create a tracked inventory item. The InventoryAssetAccountCode must correspond to an account with type INVENTORY.

 <Item>
      <Code>TrackedItem</Code>
      <PurchaseDetails>
        <COGSAccountCode>300</COGSAccountCode>
      </PurchaseDetails>
      <InventoryAssetAccountCode>630</InventoryAssetAccountCode>
    </Item>

Example – create a tracked item with full details

This example shows all the elements that can be populated on a tracked inventory item.

 <Item>
      <Code>FullTracked</Code>
      <Description>Sell me</Description>
      <PurchaseDescription>Purchase me</PurchaseDescription>
      <PurchaseDetails>
        <UnitPrice>75.5555</UnitPrice>
        <COGSAccountCode>300</COGSAccountCode>
        <TaxType>INPUT2</TaxType>
      </PurchaseDetails>
      <SalesDetails>
        <UnitPrice>1020.5555</UnitPrice>
        <AccountCode>260</AccountCode>
        <TaxType>OUTPUT2</TaxType>
      </SalesDetails>
      <Name>Full Tracked Item</Name>
      <InventoryAssetAccountCode>630</InventoryAssetAccountCode>
      <IsSold>true</IsSold>
      <IsPurchased>true</IsPurchased>
    </Item>

Adjusting the quantity and value of tracked items

The Quantity and TotalCostPool elements are read-only. They cannot be explicitly set via the Items endpoint. The only way to change the quantity and value of tracked items is by creating accounting transactions.

Increase the value and quantity of a tracked item by creating purchase transactions (ACCPAY Invoices or SPEND BankTransactions) and decrease the value and quantity of tracked items by creating sales transactions (ACCREC Invoices or RECEIVE BankTransactions). Read more about inventory adjustments in our Tracked Inventory in Xero guide.


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>
  <UpdatedDateUTC>2015-07-30T05:37:54.623</UpdatedDateUTC>
  <PurchaseDetails>
    <UnitPrice>149.0000</UnitPrice>
    <AccountCode>300</AccountCode>
  </PurchaseDetails>
  <SalesDetails>
    <UnitPrice>299.0000</UnitPrice>
    <AccountCode>200</AccountCode>
  </SalesDetails>
</Item>

Example 2. A GET request that retrieves a tracked and an untracked item

 <Items>   
   <Item>
      <ItemID>19b79d12-0ae1-496e-9649-cbd04b15c7c5</ItemID>
      <Code>UnTrackedThing</Code>
      <Description>I sell this untracked thing</Description>
      <PurchaseDescription>I buy this untracked thing</PurchaseDescription>
      <UpdatedDateUTC>2015-09-22T22:37:55.527</UpdatedDateUTC>
      <PurchaseDetails>
        <UnitPrice>20.0000</UnitPrice>
        <AccountCode>400</AccountCode>
        <TaxType>NONE</TaxType>
      </PurchaseDetails>
      <SalesDetails>
        <UnitPrice>40.0000</UnitPrice>
        <AccountCode>200</AccountCode>
        <TaxType>OUTPUT2</TaxType>
      </SalesDetails>
      <Name>An Untracked Item</Name>
      <IsTrackedAsInventory>false</IsTrackedAsInventory>
      <IsSold>true</IsSold>
      <IsPurchased>true</IsPurchased>
    </Item>
    <Item>
      <ItemID>90a72d44-43e4-410d-a68b-1139ef0c0c07</ItemID>
      <Code>TrackedThing</Code>
      <Description>I sell this tracked thing</Description>
      <PurchaseDescription>I purchase this tracked thing</PurchaseDescription>
      <UpdatedDateUTC>2015-09-22T22:42:30.547</UpdatedDateUTC>
      <PurchaseDetails>
        <UnitPrice>20.0000</UnitPrice>
        <COGSAccountCode>430</COGSAccountCode>
        <TaxType>NONE</TaxType>
      </PurchaseDetails>
      <SalesDetails>
        <UnitPrice>40.0000</UnitPrice>
        <AccountCode>200</AccountCode>
        <TaxType>OUTPUT2</TaxType>
      </SalesDetails>
      <Name>Tracked Thing</Name>
      <IsTrackedAsInventory>true</IsTrackedAsInventory>
      <InventoryAssetAccountCode>630</InventoryAssetAccountCode>
      <TotalCostPool>200.00</TotalCostPool>
      <QuantityOnHand>10.0000</QuantityOnHand>
      <IsSold>true</IsSold>
      <IsPurchased>true</IsPurchased>
    </Item>
  </Items>

DELETE Items

Delete an Item

DELETE Items/{ItemID}