> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!WARNING]
>
> **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](https://exsited.mintlify.site/api-reference/items/list-items.md) | GET | `/items` | Returns a page of items with their core fields and capability flags. |
| [Retrieve an item](https://exsited.mintlify.site/api-reference/items/retrieve-an-item.md) | GET | `/items/{item_id}` | Returns one item by its `id`, with its sale, purchase and inventory sections. |
| [Retrieve an item's information](https://exsited.mintlify.site/api-reference/items/retrieve-an-items-information.md) | GET | `/items/{item_id}/information` | Returns an item's core information, without its sale, purchase or inventory sections. |
| [Create an item](https://exsited.mintlify.site/api-reference/items/create-an-item.md) | POST | `/items` | Creates an item and returns it under `item`. |
| [Update an item's information](https://exsited.mintlify.site/api-reference/items/update-an-items-information.md) | PATCH | `/items/{item_id}/information` | Changes an item's core information and returns the item. |
| [Deactivate an item](https://exsited.mintlify.site/api-reference/items/deactivate-an-item.md) | POST | `/items/{item_id}/deactivate` | Sets an item's status to inactive and returns the item. |
| [Reactivate an item](https://exsited.mintlify.site/api-reference/items/reactivate-an-item.md) | POST | `/items/{item_id}/reactivate` | Sets a deactivated item's status back to active and returns the item. |
| [Delete an item](https://exsited.mintlify.site/api-reference/items/delete-an-item.md) | DELETE | `/items/{item_id}` | Deletes an item. A successful call returns `204` with no body. |
| [Upload an item's image](https://exsited.mintlify.site/api-reference/items/upload-an-items-image.md) | POST | `/items/{item_id}/image` | Sets an item's image from base64 text and returns the item. |
| [Retrieve an item's sale settings](https://exsited.mintlify.site/api-reference/items/retrieve-an-items-sale-settings.md) | 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](https://exsited.mintlify.site/api-reference/items/create-an-items-sale-settings.md) | POST | `/items/{item_id}/sale` | Adds a sale section to an item and returns the item. |
| [Update an item's sale settings](https://exsited.mintlify.site/api-reference/items/update-an-items-sale-settings.md) | PATCH | `/items/{item_id}/sale` | Changes part of an item's sale section and returns the item. |
| [Retrieve an item's purchase settings](https://exsited.mintlify.site/api-reference/items/retrieve-an-items-purchase-settings.md) | 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](https://exsited.mintlify.site/api-reference/items/create-an-items-purchase-settings.md) | POST | `/items/{item_id}/purchase` | Adds a purchase section to an item and returns the item. |
| [Update an item's purchase settings](https://exsited.mintlify.site/api-reference/items/update-an-items-purchase-settings.md) | 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](https://exsited.mintlify.site/api-reference/items/retrieve-an-items-inventory-settings-and-stock.md) | GET | `/items/{item_id}/inventories` | Returns an item's inventory section and its stock per warehouse. |
| [Update an item's inventory settings](https://exsited.mintlify.site/api-reference/items/update-an-items-inventory-settings.md) | PATCH | `/items/{item_id}/inventories` | Changes an item's inventory section and returns the item. |
| [Add warehouse stock](https://exsited.mintlify.site/api-reference/items/add-warehouse-stock.md) | 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](https://exsited.mintlify.site/api-reference/items/list-an-items-inventory-adjustments.md) | 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](https://exsited.mintlify.site/api-reference/items/retrieve-an-items-stock-in-one-warehouse.md) | 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](https://exsited.mintlify.site/api-reference/items/update-a-bundles-components.md) | PATCH | `/items/{item_id}/bundle_details` | Sends a bundle item's component list and returns the item. |
| [Configure an item's variations](https://exsited.mintlify.site/api-reference/items/configure-an-items-variations.md) | 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](https://exsited.mintlify.site/api-reference/items/list-an-item-familys-members.md) | GET | `/items/{item_id}/family_details` | Returns the member items of a family item. |
| [Add or remove family members](https://exsited.mintlify.site/api-reference/items/add-or-remove-family-members.md) | 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](https://exsited.mintlify.site/api-reference/items/list-an-items-packages.md) | GET | `/items/{item_id}/package_details` | Returns the packages defined on an item. |
| [Retrieve an item package](https://exsited.mintlify.site/api-reference/items/retrieve-an-item-package.md) | 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](https://exsited.mintlify.site/api-reference/items/create-an-item-package.md) | POST | `/items/{item_id}/package_details` | Adds a package to an item and returns the item. |
| [Delete an item package](https://exsited.mintlify.site/api-reference/items/delete-an-item-package.md) | 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](https://exsited.mintlify.site/api-reference/items/list-an-items-notes.md) | GET | `/items/{item_id}/notes` | Returns a page of the notes on an item. |
| [Retrieve an item note](https://exsited.mintlify.site/api-reference/items/retrieve-an-item-note.md) | GET | `/items/{item_id}/notes/{note_id}` | Returns one note on an item, under `note`. |
| [Create an item note](https://exsited.mintlify.site/api-reference/items/create-an-item-note.md) | POST | `/items/{item_id}/notes` | Adds a note to an item, with optional files, and returns the note. |
| [Update an item note](https://exsited.mintlify.site/api-reference/items/update-an-item-note.md) | PATCH | `/items/{item_id}/notes/{note_id}` | Changes a note's text, optionally adding files, and returns the note. |
| [Delete an item note](https://exsited.mintlify.site/api-reference/items/delete-an-item-note.md) | 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](https://exsited.mintlify.site/api-reference/items/list-a-notes-files.md) | GET | `/items/{item_id}/notes/{note_id}/files` | Returns the files attached to an item note. |
| [Retrieve a note file](https://exsited.mintlify.site/api-reference/items/retrieve-a-note-file.md) | 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](https://exsited.mintlify.site/api-reference/items/create-an-items-inventory-settings.md) | POST | `/items/{item_id}/inventories` | Adds an inventory section to an item and returns the whole item. |
| [Add warehouse stock (inventories path)](https://exsited.mintlify.site/api-reference/items/add-warehouse-stock-inventories-path.md) | 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)](https://exsited.mintlify.site/api-reference/items/create-an-items-inventory-settings-inventory-path.md) | POST | `/items/{item_id}/inventory` | Adds an inventory section to an item through the singular `inventory` path. |
| [Delete a note file](https://exsited.mintlify.site/api-reference/items/delete-a-note-file.md) | 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](https://exsited.mintlify.site/api-reference/items/update-an-item-package.md) | 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](https://exsited.mintlify.site/api-reference/items/retrieve-an-items-kpis.md) | 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](https://exsited.mintlify.site/authentication.md). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.