Item categories

Item-category discovery provides the account-owned category UUIDs required when creating inventory items. The endpoint is read-only and follows the API key user's current inventory permissions.

The item category object

Field	Type	Description
`id`	string	Unique item-category UUID.
`object`	string	Always `item_category`.
`name`	string	Category name.
`parent_id`	string or null	Parent category UUID, or `null` for a root category.
`inventory_type`	string	`quantity` or `unique`, based on the category's configured inventory type.
`custom_fields`	array	Category-owned custom-field definitions in display order.

Each custom-field definition contains id, name, display_order, display_on_inventory_list, and publish_on_documents. The two booleans control inventory-list metadata and public-facing document output independently.

List item categories

GET/api/v3/item-categories

Required scope: items:read

Returns item categories belonging to the current account. Categories follow their configured weight and then sort by name.

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number. Defaults to `1`.
`limit`	integer	No	Records per page from `1` to `100`. Defaults to `20`.
`q`	string	No	Searches category names.
`parent_id`	string	No	Returns direct children of a category UUID. Use `root` to return root categories.

curl "https://yourbusiness.salesbinder.com/api/v3/item-categories?parent_id=root&page=1&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "url": "/api/v3/item-categories",
  "has_more": false,
  "data": [
    {
      "id": "1c7a84de-d045-43ae-b60f-67f75f655ba0",
      "object": "item_category",
      "name": "Hardware",
      "parent_id": null,
      "inventory_type": "quantity",
      "custom_fields": [
        {
          "id": "a3c58bed-79aa-4dd4-b95a-62de877b3440",
          "name": "Material",
          "display_order": 1,
          "display_on_inventory_list": true,
          "publish_on_documents": true
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

The endpoint uses the standard page-based pagination format. Categories belonging to another account are never returned. A location-restricted user can still discover all categories in their account because categories are account-level reference data rather than location-owned records.

An invalid parent_id returns 422 invalid_query_parameter with parent_id identified as the affected parameter. Filters with no matches return an empty list.

Retrieve an item category

GET/api/v3/item-categories/{category_id}

Required scope: items:read

Returns one account-owned category with its current ordered custom_fields.

Create an item category

POST/api/v3/item-categories

Required scope: items:write

Creates an item category and its ordered custom-field definitions. The current user must also retain inventory-modify permission.

Field	Type	Required	Description
`name`	string	Yes	Category name, up to 255 characters.
`inventory_type`	string	Yes	`quantity` or `unique`.
`parent_id`	string or null	No	Top-level parent category UUID. Omit or send `null` for a root category.
`custom_fields`	array	No	Ordered custom-field definitions. Defaults to an empty array.

Each custom-field definition requires name and optionally accepts display_on_inventory_list and publish_on_documents. The array order becomes the canonical display_order.

curl "https://yourbusiness.salesbinder.com/api/v3/item-categories" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-category-001" \
  --data '{
    "name": "Camera Equipment",
    "inventory_type": "unique",
    "parent_id": null,
    "custom_fields": [
      {
        "name": "Condition Grade",
        "display_on_inventory_list": true,
        "publish_on_documents": true
      }
    ]
  }'

Returns the created category with 201 Created. Send an Idempotency-Key when a create request might be retried; an exact replay returns the original category.

Update an item category

PATCH/api/v3/item-categories/{category_id}

Required scope: items:write

Replaces the editable category definition. Send name, inventory_type, parent_id, and the complete desired custom_fields array. Include an existing custom field's id to retain it, omit id to add a field, and omit an existing field from the array to delete it. The array order becomes the canonical display_order.

An optional Idempotency-Key makes an exact retry return the original successful response. The category must belong to the current account, and the current user must retain inventory-modify permission.