Inventory Categories Management

5 API calls in this section.

List Inventory Categories

Warehousing / Inventory Categories Management

GET/warehousing/inventory-categories

Retrieves warehouse inventory categories for a tenant with filtering and pagination.

• User must have 'view:tenant' or 'manage:operations:tenant' permission

Response

• Returns a paginated list of categories

• Each category includes:

  • id, tenant_id, parent_id, name (multi-language object), description (multi-language object), is_active, sort_order, metadata, created_at, updated_at

  • parent: if the parent category is present in the current list page, a nested object with the same shape as a category (otherwise null)

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant Example: {{tenant_id}}
parent_idOptional	string	Filter by parent category ID (use 'null' for root categories). Takes precedence over root_category. (optional) Filter by parent category (UUID). Use 'null' to return only root categories. If provided, it overrides root_category. Filter by parent category ID (use 'null' for root categories). Takes precedence over root_category. (optional) Filter by parent category (UUID). Use 'null' to return only root categories. If provided, it overrides root_category.
root_categoryOptional	string	When true, only root categories (parent_id IS NULL). When false, only non-root categories (parent_id IS NOT NULL). Ignored if parent_id is provided. (optional) When true, return only root categories (parent_id IS NULL); when false, only non-root categories (parent_id IS NOT NULL). When true, only root categories (parent_id IS NULL). When false, only non-root categories (parent_id IS NOT NULL). Ignored if parent_id is provided. (optional) When true, return only root categories (parent_id IS NULL); when false, only non-root categories (parent_id IS NOT NULL).
is_activeOptional	string	Filter by active status: true or false (optional) Filter by active status (true or false) Filter by active status: true or false (optional) Filter by active status (true or false)
searchOptional	string	Search in name and description (optional, across all languages) Case-insensitive search on multilingual name and description Search in name and description (optional, across all languages) Case-insensitive search on multilingual name and description
pageOptional	string	Page number for pagination (optional, default: 1) Page number for pagination (default: 1) Page number for pagination (optional, default: 1) Page number for pagination (default: 1) Example: 1
limitOptional	string	Number of items per page (optional, default: 20) Number of items per page (default: 20) Number of items per page (optional, default: 20) Number of items per page (default: 20) Example: 20

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/warehousing/inventory-categories?tenant_id=${TENANT_ID}&parent_id=&root_category=&is_active=&search=&page=1&limit=20" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200Success Response

Response body

json

1{2  "success": true,3  "message": "Warehouse item categories retrieved successfully",4  "categories": [5    {6      "id": "cat-root-uuid",7      "tenant_id": "tenant-uuid",8      "parent_id": null,9      "name": {10        "en": "Electronics",11        "ar": "الكترونيات",12        "ku": "Elektronîk"13      },14      "description": {15        "en": "All electronic items"16      },17      "is_active": true,18      "sort_order": 0,19      "metadata": {},20      "created_at": "2025-01-01T00:00:00Z",21      "updated_at": "2025-01-01T00:00:00Z",22      "parent": null23    },24    {25      "id": "cat-child-uuid",26      "tenant_id": "tenant-uuid",27      "parent_id": "cat-root-uuid",28      "name": {29        "en": "Audio"30      },31      "description": {32        "en": "Headphones, speakers, and audio accessories"33      },34      "is_active": true,35      "sort_order": 10,36      "metadata": {},37      "created_at": "2025-01-01T00:00:00Z",38      "updated_at": "2025-01-01T00:00:00Z",39      "parent": {40        "id": "cat-root-uuid",41        "tenant_id": "tenant-uuid",42        "parent_id": null,43        "name": {44          "en": "Electronics",45          "ar": "الكترونيات",46          "ku": "Elektronîk"47        },48        "description": {49          "en": "All electronic items"50        },51        "is_active": true,52        "sort_order": 0,53        "metadata": {},54        "created_at": "2025-01-01T00:00:00Z",55        "updated_at": "2025-01-01T00:00:00Z"56      }57    }58  ],59  "page": 1,60  "limit": 20,61  "total": 262}

Create Inventory Category

Warehousing / Inventory Categories Management

POST/warehousing/inventory-categories

Creates a new warehouse inventory category.

• User must have 'manage:operations:tenant' permission

Business Rules

• name is required, must be a multi-language object, and must be unique per tenant (on the stored JSON value)

• parent_id, if provided, must reference an existing category for the same tenant

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
name	object	—
name.en	string	—
name.ar	string	—
name.ku	string	—
description	object	—
description.en	string	—
parent_id	null	—
is_active	boolean	—
sort_order	number	—
metadata	object	—
metadata.icon	string	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/warehousing/inventory-categories?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": {6    "en": "Electronics",7    "ar": "الكترونيات",8    "ku": "Elektronîk"9  },10  "description": {11    "en": "All electronic inventory items"12  },13  "parent_id": null,14  "is_active": true,15  "sort_order": 0,16  "metadata": {17    "icon": "bolt"18  }19}'

Other request examples (1)

Request example 1

text

1{2  "name": { "en": "string", "ar": "string", "ku": "string" }, // required multi-language name3  "description": { "en": "string", "ar": "string", "ku": "string" }, // optional multi-language description4  "parent_id": "uuid", // optional, parent category id or null for root5  "is_active": boolean, // optional, defaults to true6  "sort_order": number, // optional, defaults to 07  "metadata": {} // optional json object8}

Response examples

201Success Response

Response body

json

1{2  "success": true,3  "message": "Warehouse item category created successfully",4  "category": {5    "id": "new-category-uuid",6    "tenant_id": "tenant-uuid",7    "parent_id": null,8    "name": {9      "en": "Electronics"10    },11    "description": {12      "en": "All electronic inventory items"13    },14    "is_active": true,15    "sort_order": 0,16    "metadata": {17      "icon": "bolt"18    },19    "created_at": "2025-01-01T10:00:00Z",20    "updated_at": "2025-01-01T10:00:00Z"21  }22}

Get Inventory Category

Warehousing / Inventory Categories Management

GET/warehousing/inventory-categories/:id

Retrieves a single warehouse inventory category by ID.

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory category (required) UUID of the inventory category (required) Example: category-uuid

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/warehousing/inventory-categories/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200Success Response

Response body

json

1{2  "success": true,3  "message": "Warehouse item category retrieved successfully",4  "category": {5    "id": "category-uuid",6    "tenant_id": "tenant-uuid",7    "parent_id": "parent-category-uuid",8    "name": {9      "en": "Electronics"10    },11    "description": {12      "en": "All electronic inventory items"13    },14    "is_active": true,15    "sort_order": 0,16    "metadata": {},17    "created_at": "2025-01-01T00:00:00Z",18    "updated_at": "2025-01-01T00:00:00Z",19    "parent": {20      "id": "parent-category-uuid",21      "tenant_id": "tenant-uuid",22      "parent_id": null,23      "name": {24        "en": "Root Category"25      },26      "description": {27        "en": "Parent category description"28      },29      "is_active": true,30      "sort_order": 0,31      "metadata": {},32      "created_at": "2025-01-01T00:00:00Z",33      "updated_at": "2025-01-01T00:00:00Z"34    }35  }36}

Update Inventory Category

Warehousing / Inventory Categories Management

PUT/warehousing/inventory-categories/:id

Updates an existing warehouse inventory category. Only provided fields will be updated.

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory category to update (required) UUID of the inventory category to update (required) Example: category-uuid

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Body parameters

Parameter	Type	Description
name	object	—
name.en	string	—
description	object	—
description.en	string	—
is_active	boolean	—
sort_order	number	—
metadata	object	—
metadata.icon	string	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/warehousing/inventory-categories/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": {6    "en": "Electronics & Gadgets"7  },8  "description": {9    "en": "Updated description for electronics inventory items"10  },11  "is_active": true,12  "sort_order": 5,13  "metadata": {14    "icon": "bolt"15  }16}'

Response examples

200Success Response

Response body

json

1{2  "success": true,3  "message": "Warehouse item category updated successfully",4  "category": {5    "id": "category-uuid",6    "tenant_id": "tenant-uuid",7    "parent_id": null,8    "name": {9      "en": "Electronics & Gadgets"10    },11    "description": {12      "en": "Updated description for electronics inventory items"13    },14    "is_active": true,15    "sort_order": 5,16    "metadata": {17      "icon": "bolt"18    },19    "created_at": "2025-01-01T00:00:00Z",20    "updated_at": "2025-01-02T10:00:00Z"21  }22}

Delete Inventory Category

Warehousing / Inventory Categories Management

DELETE/warehousing/inventory-categories/:id

Deletes a warehouse inventory category.

Note

This performs a hard delete. Make sure the category is not in use before calling this endpoint.

Path parameters

Parameter	Type	Description
idRequired	string	UUID of the inventory category to delete (required) UUID of the inventory category to delete (required) Example: category-uuid

Query parameters

Parameter	Type	Description
tenant_id	string	UUID of the tenant (required if not in auth) UUID of the tenant (required if not in auth) Example: {{tenant_id}}

Headers

Parameter	Type	Description
Authorization	string	Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/warehousing/inventory-categories/${ID}?tenant_id=${TENANT_ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200Success Response

Response body

json

1{2  "success": true,3  "message": "Warehouse item category deleted successfully",4  "id": "category-uuid"5}