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.

GET Items

Use this method to retrieve either one or many items.

The following elements are returned in the Items response:

ItemIDXero generated identifier for an item
CodeUser defined item code
NameThe name of the item
IsSoldBoolean value. When IsSold is true the item will be available on sales transactions in the Xero UI.
IsPurchasedBoolean value. When IsPurchased is true the item is available for purchase transactions in the Xero UI.
DescriptionThe sales description of the item
PurchaseDescriptionThe purchase description of the item
PurchaseDetailsSee Purchases & Sales. The PurchaseDetails element can contain a number of individual sub-elements.
SalesDetailsSee Purchases & Sales. The SalesDetails element can contain a number of individual sub-elements.
IsTrackedAsInventoryTrue for items that are tracked as inventory. An item will be tracked as inventory if the InventoryAssetAccountCode and COGSAccountCode are set.
InventoryAssetAccountCodeThe 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
TotalCostPoolThe value of the item on hand. Calculated using average cost accounting.
QuantityOnHandThe quantity of the item on hand
UpdatedDateUTCLast modified date in UTC format
Elements for Purchases and Sales
UnitPriceUnit Price of the item. By default UnitPrice is returned to two decimal places. You can use 4 decimal places by adding the unitdp=4 querystring parameter to your request.
AccountCodeDefault account code to be used for purchased/sale. Not applicable to the purchase details of tracked items
COGSAccountCodeCost of goods sold account. Only applicable to the purchase details of tracked items.
TaxTypeUsed as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes.

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 response when retrieving an individual item

GET https://api.xero.com/api.xro/2.0/Items/Merino-2011-LG
<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>

Examples response when retrieving a collection of items

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

POST Items

Use this method to create or update items.

Elements for Items

The following is required for a PUT / POST
CodeUser defined item code (max length = 30)
The following is required for a PUT / POST on a tracked inventory item
InventoryAssetAccountCodeThe 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
NameThe name of the item (max length = 50)
IsSoldBoolean 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.
IsPurchasedBoolean 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.
DescriptionThe sales description of the item (max length = 4000)
PurchaseDescriptionThe purchase description of the item (max length = 4000)
PurchaseDetailsSee Purchases & Sales. The PurchaseDetails element can contain a number of individual sub-elements.
SalesDetailsSee Purchases & Sales. The SalesDetails element can contain a number of individual sub-elements.
Elements for Purchases and Sales
UnitPriceUnit 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.
AccountCodeDefault account code to be used for purchased/sale. Not applicable to the purchase details of tracked items
COGSAccountCodeCost of goods sold account. Only applicable to the purchase details of tracked items.
TaxTypeUsed as an override if the default Tax Code for the selected AccountCode is not correct - see TaxTypes.

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.

Example request with minimum elements to create an untracked item

POST https://api.xero.com/api.xro/2.0/Items
<Item>
  <Code>Item-1</Code>
 </Item>

Example request to create an untracked item with sales and purchase details

POST https://api.xero.com/api.xro/2.0/Items
<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 request with minimum elements to create a tracked item

POST https://api.xero.com/api.xro/2.0/Items
<Item>
  <Code>TrackedItem</Code>
  <PurchaseDetails>
   <COGSAccountCode>300</COGSAccountCode>
  </PurchaseDetails>
  <InventoryAssetAccountCode>630</InventoryAssetAccountCode>
</Item>

Example request to create a tracked item with full details

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

PUT Items

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

DELETE Items

Use the DELETE method to delete items

Example request to delete an item

DELETE https://api.xero.com/api.xro/2.0/Items/297c2dc5-cc47-4afd-8ec8-74990b8761e9