# Folders

Folders are how you organize inventory by location, category, job, or whatever fits
how you work. They can be nested, and items live inside them.

Folders use the same endpoints as items, with `"type": "folder"` and no quantity or
price. Nest one inside another by setting `parent_id`; leave it out for the top level.
To list a folder's contents, pass its id as `folder_id` when listing items.


## Create

 - [POST /api/v1/items](https://developer.sortly.com/items/createitem.md): Creates a new item or folder.

- type is "item" for a trackable inventory object, or "folder" for a container.
- parent_id places it inside a folder. Omit it or pass null for the root level.
- To attach custom field values, call GET /custom_fields first to discover valid
  custom_attribute_id values.

## List

 - [GET /api/v1/items](https://developer.sortly.com/items/listitems.md): Returns a paginated list of items and folders. By default returns root-level items.
Use folder_id to list the contents of a specific folder. Pass include=custom_attributes,photos,options to embed nested associations in the response.
Results are ordered by created_at descending.

## Delete

 - [DELETE /api/v1/items/{item_id}](https://developer.sortly.com/items/deleteitem.md): Permanently deletes an item or folder by its numeric ID. Deleting a folder also deletes all items and sub-folders it contains.
This action is irreversible. Returns an empty {} body on success.

## Fetch

 - [GET /api/v1/items/{item_id}](https://developer.sortly.com/items/fetchitem.md): Returns a single item or folder by its numeric ID.
Pass include=custom_attributes,photos,options to embed custom field values, photo URLs, and variant option values in the response.

## Update

 - [PUT /api/v1/items/{item_id}](https://developer.sortly.com/items/updateitem.md): Updates fields on an existing item or folder. Only fields you include in the request body are changed. Omitted fields keep their current values.
To clear a field, pass it explicitly as null. Returns 204 No Content on success.

## Move

 - [POST /api/v1/items/{item_id}/move](https://developer.sortly.com/items/moveitem.md): Moves a quantity of an item to a different folder. The moved portion becomes a separate
item in the destination, with its own id and the same sid.

- folder_id is the destination. Pass null to move to the root level.
- leave_zero_quantity: true keeps a zero-quantity record in the source folder. The
  default, false, removes the source item once its quantity reaches 0.

## Create

 - [POST /api/v1/items](https://developer.sortly.com/folders/createitem.md): Creates a new item or folder.

- type is "item" for a trackable inventory object, or "folder" for a container.
- parent_id places it inside a folder. Omit it or pass null for the root level.
- To attach custom field values, call GET /custom_fields first to discover valid
  custom_attribute_id values.

## List

 - [GET /api/v1/items](https://developer.sortly.com/folders/listitems.md): Returns a paginated list of items and folders. By default returns root-level items.
Use folder_id to list the contents of a specific folder. Pass include=custom_attributes,photos,options to embed nested associations in the response.
Results are ordered by created_at descending.

## Delete

 - [DELETE /api/v1/items/{item_id}](https://developer.sortly.com/folders/deleteitem.md): Permanently deletes an item or folder by its numeric ID. Deleting a folder also deletes all items and sub-folders it contains.
This action is irreversible. Returns an empty {} body on success.

## Fetch

 - [GET /api/v1/items/{item_id}](https://developer.sortly.com/folders/fetchitem.md): Returns a single item or folder by its numeric ID.
Pass include=custom_attributes,photos,options to embed custom field values, photo URLs, and variant option values in the response.

## Update

 - [PUT /api/v1/items/{item_id}](https://developer.sortly.com/folders/updateitem.md): Updates fields on an existing item or folder. Only fields you include in the request body are changed. Omitted fields keep their current values.
To clear a field, pass it explicitly as null. Returns 204 No Content on success.

## Move

 - [POST /api/v1/items/{item_id}/move](https://developer.sortly.com/folders/moveitem.md): Moves a quantity of an item to a different folder. The moved portion becomes a separate
item in the destination, with its own id and the same sid.

- folder_id is the destination. Pass null to move to the root level.
- leave_zero_quantity: true keeps a zero-quantity record in the source folder. The
  default, false, removes the source item once its quantity reaches 0.