Returns the item categories that match the given criteria.

POST /inventory/item-categories/search

Group: Inventory › Item Categories · Operation ID: searchItemCategories

Searches item categories by exact criteria in a request body, returning the same schema as GET inventory/item-categories/:id and GET inventory/item-categories.

Every field on an item category is a plain scalar, so the collection can already express every filter offered here. This endpoint adds a request body, for a query assembled programmatically or one that would push a URL past a proxy's length limit, and a larger page size. There is no free-text or substring matching, which is why description is not a criterion.

Nothing matching is an empty result, never an error.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchItemCategoriesInput.

Field Type Required Description
filters object yes The filters to apply. Omit to return all item categories.
filters.name string no Limits results to item categories with this exact name, for example 'Hardware'. Names are not unique, so this can match several.
filters.active boolean no Limits results to categories that can be chosen on new items (true) or to retired ones (false). Omit to match both.
filters.modifiedSince string (date-time) no Limits results to categories changed at or after this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
page object no Pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit on the first request.
page.size number no The number of item categories per page. Defaults to 50, capped at 200.

Example:

{
  "filters": {
    "active": true,
    "modifiedSince": "2026-08-01T00:00:00.000Z"
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchItemCategoriesOutput):

Field Type Required Description
items array of object yes The item categories on this page, ordered by id. The same schema as GET inventory/item-categories/:id. An empty array when nothing matches.
items[].id string yes The unique identifier for the item category.
items[].name string yes The display name of the category, for example 'Hardware'. Not unique: two categories can share a name, so use id to address one.
items[].description string no A free-form description of what the category covers. Absent when none was set.
items[].active boolean no Whether the category can be chosen on new items. When false the category is retired: existing items keep it and new ones cannot be assigned to it.
items[].idealTurnoverRatio string (decimal) no The target inventory turnover for items in this category, in times per year. For analytics only. A ratio rather than an amount, so it has no currency.
items[].lastModifiedDate string (date-time) no The date and time the category last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].parentId string no The identifier of the category this one sits under. Absent for a top-level category. See id on GET inventory/item-categories/:id.
pagination object yes The pagination details for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes Whether more results remain beyond this page.

Statuses