Search item categories

Operation ID: searchItemCategories

Group: Inventory › Item Categories

Open in the interactive reference

POST /inventory/item-categories/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches item categories. The filters are name, active, and modifiedSince, sent in the request body. The fields are the same as on GET inventory/item-categories/:id.

Parameters

Name In Type Required Description
Api-Version header string · 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. Example: {"active":true,"modifiedSince":"2026-08-01T00:00:00.000Z"}.
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 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. Example: {"size":50}.
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. 
{
  "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<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. Example: [{"id":"a2f47b91-0c6d-4e38-95b1-7d3e6a428c50","name":"Hardware","description":"Fasteners, fittings and tooling","active":true,"idealTurnoverRatio":"6.50","lastModifiedDate":"2026-08-03T11:15:00.000Z"}].
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 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 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. Example: {"hasMore":false}.
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. 
{
  "data": {
    "items": [
      {
        "id": "a2f47b91-0c6d-4e38-95b1-7d3e6a428c50",
        "name": "Hardware",
        "description": "Fasteners, fittings and tooling",
        "active": true,
        "idealTurnoverRatio": "6.50",
        "lastModifiedDate": "2026-08-03T11:15:00.000Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Statuses