Menu

Inventory Items API Routes

An inventory item is a stock-kept product whose inventory is managed.

These API routes allow admin users to manage inventory items.

GET /admin/inventory-items#

List Inventory Items

Retrieve a list of inventory items. The inventory items can be filtered by fields such as id. The inventory items can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
The inventory item's q.
idstring | string[]Optional
The inventory item's ID.
skustring | string[]Optional
The inventory item's sku.
origin_countrystring | string[]Optional
The inventory item's origin country.
mid_codestring | string[]Optional
The inventory item's mid code.
hs_codestring | string[]Optional
The inventory item's hs code.
materialstring | string[]Optional
The inventory item's material.
requires_shippingbooleanOptional
The inventory item's requires shipping.
weightobjectOptional
Filter the inventory item's weight. Accepts the filter operators.
lengthobjectOptional
Filter the inventory item's length. Accepts the filter operators.
heightobjectOptional
Filter by the inventory item's height. Accepts the filter operators.
widthobjectOptional
Filter by the inventory item's width. Accepts the filter operators.
location_levelsobjectOptional
Filter by the inventory item's associated location IDs.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
inventory_itemsobject[]
The inventory item's inventory items.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/inventory-items#

Create Inventory Item

Create an inventory item.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

skustringOptional
The inventory item's SKU.
hs_codestringOptional
The inventory item's HS code.
weightnumberOptional
The inventory item's weight.
lengthnumberOptional
The inventory item's length.
heightnumberOptional
The inventory item's height.
widthnumberOptional
The inventory item's width.
origin_countrystringOptional
The inventory item's origin country.
mid_codestringOptional
The inventory item's mid code.
materialstringOptional
The inventory item's material.
titlestringOptional
The inventory item's title.
descriptionstringOptional
The description of the variant associated with the inventory item.
requires_shippingbooleanOptional
Whether the item requires shipping.
thumbnailstringOptional
The inventory item's thumbnail.
metadataobjectOptional
The inventory item's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.
location_levelsobject[]Optional
The inventory item's location levels.
unit_of_measurestringOptional
The inventory item's unit of measure.
Example: kg

Request examples

Responses

200 OK

inventory_itemobject
The inventory item's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-item.created: Emitted when inventory items are created.
  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/inventory-items/export#

Export Inventory Items

Start an inventory items export process to retrieve a CSV of exported inventory items.

You'll receive in the response the transaction ID of the workflow generating the CSV file. To check the status of the execution, send a GET request to /admin/workflows-executions/export-inventory-items/:transaction-id. Once the execution finishes successfully, a notification is created for the export. You can retrieve the notifications using the /admin/notification API route to retrieve the file's download URL.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

idstring | string[]Optional
The ID of the inventory item to export.
qstringOptional
Search query to apply on inventory item searchable fields to filter the results.
skustring | string[]Optional
Filter by the inventory item's sku.
origin_countrystring | string[]Optional
Filter by the inventory item's origin country.
mid_codestring | string[]Optional
Filter by the inventory item's mid code.
hs_codestring | string[]Optional
Filter by the inventory item's hs code.
materialstring | string[]Optional
Filter by the inventory item's material.
requires_shippingbooleanOptional
Filter by whether the inventory item requires shipping.
weightnumber | objectOptional
Filter by the inventory item's weight. Accepts the filter operators.
lengthnumber | objectOptional
Filter by the inventory item's length. Accepts the filter operators.
heightnumber | objectOptional
Filter by the inventory item's height. Accepts the filter operators.
widthnumber | objectOptional
Filter by the inventory item's width. Accepts the filter operators.
location_levelsobjectOptional
Filter by the inventory item's location levels.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
Whether to include soft-deleted items in the results.
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.

Request examples

Responses

202 OK

transaction_idstring
The ID of the workflow execution's transaction. Use it to check the status of the export by sending a GET request to /admin/workflows-executions/export-inventory-items/:transaction-id

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/inventory-items/location-levels/batch#

Manage Inventory Levels

Manage inventory levels to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

createobject[]Optional
The inventory levels to create.
updateobject[]Optional
The inventory levels to update.
deletestring[]Optional
The IDs of the inventory levels to delete.
forcebooleanOptional
Whether to delete specified inventory levels even if they have a non-zero stocked quantity.

Request examples

Responses

200 OK

createdobject[]Optional
The created inventory levels.
updatedobject[]Optional
The updated inventory levels.
deletedstring[]Optional
The IDs of deleted inventory levels.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-level.created: Emitted when inventory levels are created.
  • inventory-level.updated: Emitted when inventory levels are updated. This includes adjustments to the stocked or reserved quantity, such as during order fulfillment.
  • inventory-level.deleted: Emitted when inventory levels are deleted.

GET /admin/inventory-items/{id}#

Get a Inventory Item

Retrieve a inventory item by its ID. You can expand the inventory item's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

inventory_itemobject
The inventory item's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/inventory-items/{id}#

Update an Inventory Item

Update an inventory item's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

skustringOptional
The inventory item's SKU.
hs_codestringOptional
The inventory item's HS code.
weightnumberOptional
The inventory item's weight.
lengthnumberOptional
The inventory item's length.
heightnumberOptional
The inventory item's height.
widthnumberOptional
The inventory item's width.
origin_countrystringOptional
The inventory item's origin country.
mid_codestringOptional
The inventory item's MID code.
materialstringOptional
The inventory item's material.
titlestringOptional
The inventory item's title.
descriptionstringOptional
The inventory item's description.
requires_shippingbooleanOptional
Whether the inventory item requires shipping.
thumbnailstringOptional
The URL of an image to be used as the inventory item's thumbnail. You can use the Upload API routes to upload an image and get its URL.
metadataobjectOptional
The inventory item's metadata. Can be custom data in key-value pairs. Learn more in the Manage Metadata section.
unit_of_measurestringOptional
The inventory item's unit of measure.
Example: kg

Request examples

Responses

200 OK

inventory_itemobject
The inventory item's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-item.updated: Emitted when inventory items are updated.

DELETE /admin/inventory-items/{id}#

Delete Inventory Item

Delete an inventory item.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.

Request examples

Responses

200 OK

idstring
The inventory item's ID.
objectstring
The name of the deleted object.

Default: "inventory_item"

deletedboolean
Whether the inventory item was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-item.deleted: Emitted when inventory items are deleted.

GET /admin/inventory-items/{id}/location-levels#

List Inventory Levels

Retrieve a list of inventory levels associated with an inventory item. The inventory levels can be filtered by fields like location_id. The inventory levels can also be paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
Whether to include deleted records in the result.
location_idstring | string[]Optional
Filter by the inventory item's location ID.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
inventory_levelsobject[]
The inventory item's inventory levels.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/inventory-items/{id}/location-levels#

Create Inventory Level for Inventory Item

Create an inventory level for an inventory item.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

location_idstring
The ID of the associated location.
stocked_quantitynumberOptional
The inventory level's stocked quantity.
incoming_quantitynumberOptional
The inventory level's incoming quantity.

Request examples

Responses

200 OK

inventory_itemobject
The inventory item's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-level.created: Emitted when inventory levels are created.

POST /admin/inventory-items/{id}/location-levels/batch#

Manage Inventory Levels of Inventory Item

Manage the inventory levels of an inventory item to create or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.

Request body (application/json)

createobject[]Optional
The inventory levels to create.
updateobject[]Optional
The inventory levels to update.
deletestring[]Optional
The inventory levels to delete.
forcebooleanOptional
Whether to delete specified inventory levels even if they have a non-zero stocked quantity.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-level.created: Emitted when inventory levels are created.
  • inventory-level.updated: Emitted when inventory levels are updated. This includes adjustments to the stocked or reserved quantity, such as during order fulfillment.
  • inventory-level.deleted: Emitted when inventory levels are deleted.

POST /admin/inventory-items/{id}/location-levels/{location_id}#

Update an Inventory Level of an Inventory Item

Updates the details of an inventory item's inventory level using its associated location ID.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.
location_idstring
The ID of the location associated with the inventory level.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

stocked_quantitynumberOptional
The inventory level's stocked quantity.
incoming_quantitynumberOptional
The inventory level's incoming quantity.

Request examples

Responses

200 OK

inventory_itemobject
The inventory item's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-level.updated: Emitted when inventory levels are updated. This includes adjustments to the stocked or reserved quantity, such as during order fulfillment.

DELETE /admin/inventory-items/{id}/location-levels/{location_id}#

Remove Inventory Level of Inventory Item

Remove the inventory level of an inventory item.

If the inventory level has reserved quantity greater than 0, an error is thrown.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The inventory item's ID.
location_idstring
The inventory item's location id.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

idstring
The inventory item's ID.
objectstring
The name of the deleted object.
deletedboolean
Whether the Inventory Item was deleted.
parentobjectOptional
The inventory item's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • inventory-level.deleted: Emitted when inventory levels are deleted.
Found a problem with this page?Report Issue
Edited Nov 14·Edit this page