Items

List, read, create, update and delete items, set their sale, purchase and inventory sections, add stock, and manage bundles, families, packages and notes.

Items are the products and services you sell and buy. These endpoints create, read, update and delete items, set their sale, purchase and inventory sections, add stock to warehouses, and manage bundles, families, variations, packages and notes. This area has 41 endpoints, each available in all seven SDKs.

An item that an order references cannot be deleted. The delete returns 409, and retrying does not help.

At a glance

Endpoint	Method	Path	What it does
List items	GET	/items	Returns a page of items with their core fields and capability flags.
Retrieve an item	GET	/items/{item_id}	Returns one item by its id, with its sale, purchase and inventory sections.
Retrieve an item’s information	GET	/items/{item_id}/information	Returns an item’s core information, without its sale, purchase or inventory sections.
Create an item	POST	/items	Creates an item and returns it under item.
Update an item’s information	PATCH	/items/{item_id}/information	Changes an item’s core information and returns the item.
Deactivate an item	POST	/items/{item_id}/deactivate	Sets an item’s status to inactive and returns the item.
Reactivate an item	POST	/items/{item_id}/reactivate	Sets a deactivated item’s status back to active and returns the item.
Delete an item	DELETE	/items/{item_id}	Deletes an item. A successful call returns 204 with no body.
Upload an item’s image	POST	/items/{item_id}/image	Sets an item’s image from base64 text and returns the item.
Retrieve an item’s sale settings	GET	/items/{item_id}/sale	Returns an item’s sale section in a short item with id, name and sale.
Create an item’s sale settings	POST	/items/{item_id}/sale	Adds a sale section to an item and returns the item.
Update an item’s sale settings	PATCH	/items/{item_id}/sale	Changes part of an item’s sale section and returns the item.
Retrieve an item’s purchase settings	GET	/items/{item_id}/purchase	Returns an item’s purchase section in a short item with id, name and purchase.
Create an item’s purchase settings	POST	/items/{item_id}/purchase	Adds a purchase section to an item and returns the item.
Update an item’s purchase settings	PATCH	/items/{item_id}/purchase	Changes part of an item’s purchase section and returns the item.
Retrieve an item’s inventory settings and stock	GET	/items/{item_id}/inventories	Returns an item’s inventory section and its stock per warehouse.
Update an item’s inventory settings	PATCH	/items/{item_id}/inventories	Changes an item’s inventory section and returns the item.
Add warehouse stock	POST	/items/{item_id}/inventory/add	Adds stock to one or more of an item’s warehouses and returns the item.
List an item’s inventory adjustments	GET	/items/{item_id}/inventory_adjustments	Returns a page of the stock changes made to one item.
Retrieve an item’s stock in one warehouse	GET	/items/{item_id}/warehouses/{warehouse_name}/inventories	Returns an item’s inventory section for one warehouse, named in the path.
Update a bundle’s components	PATCH	/items/{item_id}/bundle_details	Sends a bundle item’s component list and returns the item.
Configure an item’s variations	PATCH	/items/{item_id}/variations	Sets the variation options of a parent item, or the options a child item uses.
List an item family’s members	GET	/items/{item_id}/family_details	Returns the member items of a family item.
Add or remove family members	POST	/items/{item_id}/family_details	Adds member items to a family item, or removes them, and returns the item.
List an item’s packages	GET	/items/{item_id}/package_details	Returns the packages defined on an item.
Retrieve an item package	GET	/items/{item_id}/package_details/{package_detail_id}	Returns one of an item’s packages, by the package’s uuid.
Create an item package	POST	/items/{item_id}/package_details	Adds a package to an item and returns the item.
Delete an item package	DELETE	/items/{item_id}/package_details/{package_detail_id}	Deletes one of an item’s packages. A successful call returns 204 with no body.
List an item’s notes	GET	/items/{item_id}/notes	Returns a page of the notes on an item.
Retrieve an item note	GET	/items/{item_id}/notes/{note_id}	Returns one note on an item, under note.
Create an item note	POST	/items/{item_id}/notes	Adds a note to an item, with optional files, and returns the note.
Update an item note	PATCH	/items/{item_id}/notes/{note_id}	Changes a note’s text, optionally adding files, and returns the note.
Delete an item note	DELETE	/items/{item_id}/notes/{note_id}	Deletes a note from an item. A successful call returns 204 with no body.
List a note’s files	GET	/items/{item_id}/notes/{note_id}/files	Returns the files attached to an item note.
Retrieve a note file	GET	/items/{item_id}/notes/{note_id}/files/{file_id}	Returns the details of one file on an item note.
Create an item’s inventory settings	POST	/items/{item_id}/inventories	Adds an inventory section to an item and returns the whole item.
Add warehouse stock (inventories path)	POST	/items/{item_id}/inventories/add	Adds stock to an item’s warehouses through the plural inventories/add path.
Create an item’s inventory settings (inventory path)	POST	/items/{item_id}/inventory	Adds an inventory section to an item through the singular inventory path.
Delete a note file	DELETE	/items/{item_id}/notes/{note_id}/files/{file_id}	Deletes one file from an item note. A successful call returns 204 with no body.
Update an item package	PATCH	/items/{item_id}/package_details/{package_detail_id}	Changes one of an item’s packages and returns the item.
Retrieve an item’s KPIs	GET	/items/{item_id}/kpis	Returns an item’s KPI summary under item_kpis.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Every item JSON write is wrapped in item. Two writes are not: the image upload sends image_base64 at the top level, and the note writes are multipart forms with a note field.
• Address an item by its id, such as ITEM-0001. Not by its uuid, and not by the integer id that the sale and purchase reads return.
• type and name are the minimum to create an item. Send type in upper case, such as STANDARD, BUNDLE, FAMILY or VARIATION_BASED; it comes back in lower case.
• The item listing pages by cursor and filters with filter_<field>. Pass limit, then send the next_cursor from pagination as cursor; has_more tells you when to stop. Filter with filter_<field>; a bare filter expression is refused with 400.
• The sale, purchase and inventories reads return a short item. Each carries id, name and its one section, and the sale and purchase reads give id as an integer.
• Item notes are sent as a multipart form. The text goes in the note field, and files are optional extra parts.