Xero: Updates or creates one or more items

← Accounting operations · Get started

Operation xero.updateorcreateitems

Provider route: POST /api.xro/2.0/Items. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/xero with npm, or alter-sdk-xero with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { XeroIntegration } from "@alter-ai/xero";

async function execute(input: Parameters<XeroIntegration["accounting"]["updateOrCreateItems"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new XeroIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.accounting.updateOrCreateItems(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_xero import XeroIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = XeroIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.accounting.update_or_create_items(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.summarizeErrors	boolean	Optional	Default: false
query.unitdp	integer	Optional
headers	object	Required within parent	Additional keys: not allowed
headers.xero-tenant-id	string	Required within parent
headers.Idempotency-Key	string	Optional
body	Model	Required within parent	Expand Updates a specific item — request body — body

Referenced models: Updates a specific item — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Retrieves items — response body

Referenced models: Retrieves items — response body

Schemas

Updates a specific item — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
Items	array	Optional
Items[]	Model	Each item	Expand Updates a specific item — request body — body Items item

Referenced models: Updates a specific item — request body — body Items item

Retrieves items — response body

Field	Type	Presence	Description and constraints
$	object	Root
Items	array	Optional
Items[]	Model	Each item	Expand Retrieves items — response body — Items item

Referenced models: Retrieves items — response body — Items item

Updates a specific item — request body — body Items item

Field	Type	Presence	Description and constraints
$	object	Root
Code	string	Required within parent	User defined item code (max length = 30) Maximum length: 30
Description	string	Optional	The sales description of the item (max length = 4000) Maximum length: 4000
InventoryAssetAccountCode	string	Optional	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
IsPurchased	boolean	Optional	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.
IsSold	boolean	Optional	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.
IsTrackedAsInventory	boolean	Optional	True for items that are tracked as inventory. An item will be tracked as inventory if the InventoryAssetAccountCode and COGSAccountCode are set.
ItemID	string	Optional	The Xero identifier for an Item Format: uuid
Name	string	Optional	The name of the item (max length = 50) Maximum length: 50
PurchaseDescription	string	Optional	The purchase description of the item (max length = 4000) Maximum length: 4000
PurchaseDetails	Model	Optional	Expand Updates a specific item — request body — body Items item Sales Details
QuantityAvailable	number	Optional	The quantity of the item available. This is equal to `QuantityOnHand` - `QuantityOnBackOrder`. This value will be negative if `QuantityOnBackOrder` is greater than 0. Format: double Read only: true
QuantityOnBackOrder	number	Optional	The quantity of the item on backorder. This will be 0 if `QuantityOnHand` is greater than 0. Format: double Read only: true
QuantityOnHand	number	Optional	The quantity of the item on hand. This will be 0 if `QuantityOnBackOrder` is greater than 0. Format: double
SalesDetails	Model	Optional	Expand Updates a specific item — request body — body Items item Sales Details
StatusAttributeString	string	Optional	Status of object
TotalCostPool	number	Optional	The value of the item on hand. Calculated using average cost accounting. Format: double
UpdatedDateUTC	string	Optional	Last modified date in UTC format Read only: true
ValidationErrors	array	Optional	Displays array of validation error messages from the API
ValidationErrors[]	Model	Each item	Expand Retrieves journals — response body — Warnings item

Referenced models: Retrieves journals — response body — Warnings item, Updates a specific item — request body — body Items item Sales Details

Retrieves items — response body — Items item

Field	Type	Presence	Description and constraints
$	object	Root
Code	string	Required within parent	User defined item code (max length = 30) Maximum length: 30
Description	string	Optional	The sales description of the item (max length = 4000) Maximum length: 4000
InventoryAssetAccountCode	string	Optional	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
IsPurchased	boolean	Optional	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.
IsSold	boolean	Optional	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.
IsTrackedAsInventory	boolean	Optional	True for items that are tracked as inventory. An item will be tracked as inventory if the InventoryAssetAccountCode and COGSAccountCode are set.
ItemID	string	Optional	The Xero identifier for an Item Format: uuid
Name	string	Optional	The name of the item (max length = 50) Maximum length: 50
PurchaseDescription	string	Optional	The purchase description of the item (max length = 4000) Maximum length: 4000
PurchaseDetails	Model	Optional	Expand Retrieves items — response body — Items item Sales Details
QuantityAvailable	JSON	Optional
QuantityAvailable (anyOf 1)	number	Alternative	The quantity of the item available. This is equal to `QuantityOnHand` - `QuantityOnBackOrder`. This value will be negative if `QuantityOnBackOrder` is greater than 0. Format: double Read only: true
QuantityAvailable (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
QuantityOnBackOrder	JSON	Optional
QuantityOnBackOrder (anyOf 1)	number	Alternative	The quantity of the item on backorder. This will be 0 if `QuantityOnHand` is greater than 0. Format: double Read only: true
QuantityOnBackOrder (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
QuantityOnHand	JSON	Optional
QuantityOnHand (anyOf 1)	number	Alternative	The quantity of the item on hand. This will be 0 if `QuantityOnBackOrder` is greater than 0. Format: double
QuantityOnHand (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
SalesDetails	Model	Optional	Expand Retrieves items — response body — Items item Sales Details
StatusAttributeString	string	Optional	Status of object
TotalCostPool	JSON	Optional
TotalCostPool (anyOf 1)	number	Alternative	The value of the item on hand. Calculated using average cost accounting. Format: double
TotalCostPool (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
UpdatedDateUTC	string	Optional	Last modified date in UTC format Read only: true
ValidationErrors	array	Optional	Displays array of validation error messages from the API
ValidationErrors[]	Model	Each item	Expand Retrieves journals — response body — Warnings item

Referenced models: Retrieves items — response body — Items item Sales Details, Retrieves journals — response body — Warnings item

Retrieves journals — response body — Warnings item

Field	Type	Presence	Description and constraints
$	object	Root
Message	string	Optional	Validation error message

Updates a specific item — request body — body Items item Sales Details

Field	Type	Presence	Description and constraints
$	object	Root
AccountCode	string	Optional	Default account code to be used for purchased/sale. Not applicable to the purchase details of tracked items
COGSAccountCode	string	Optional	Cost of goods sold account. Only applicable to the purchase details of tracked items.
TaxType	string	Optional	The tax type from TaxRates
UnitPrice	number	Optional	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. Format: double

Retrieves items — response body — Items item Sales Details

Field	Type	Presence	Description and constraints
$	object	Root
AccountCode	string	Optional	Default account code to be used for purchased/sale. Not applicable to the purchase details of tracked items
COGSAccountCode	string	Optional	Cost of goods sold account. Only applicable to the purchase details of tracked items.
TaxType	string	Optional	The tax type from TaxRates
UnitPrice	JSON	Optional
UnitPrice (anyOf 1)	number	Alternative	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. Format: double
UnitPrice (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Policy, approvals and errors

SDK function policy ID: xero.updateorcreateitems. Catalog operation: updateOrCreateItems. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source