Skip to main content

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

ParameterTypeDescription
tenant_idstring

UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant

Example: {{tenant_id}}

parent_idOptionalstring

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_categoryOptionalstring

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_activeOptionalstring

Filter by active status: true or false (optional) Filter by active status (true or false)

searchOptionalstring

Search in name and description (optional, across all languages) Case-insensitive search on multilingual name and description

pageOptionalstring

Page number for pagination (optional, default: 1) Page number for pagination (default: 1)

Example: 1

limitOptionalstring

Number of items per page (optional, default: 20) Number of items per page (default: 20)

Example: 20

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

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

ParameterTypeDescription
tenant_idstring

UUID of the tenant (required if not in auth) (required if not in auth): UUID of the tenant

Example: {{tenant_id}}

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
nameobject—
name.enstring—
name.arstring—
name.kustring—
descriptionobject—
description.enstring—
parent_idnull—
is_activeboolean—
sort_ordernumber—
metadataobject—
metadata.iconstring—
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

ParameterTypeDescription
idRequiredstring

UUID of the inventory category (required)

Example: category-uuid

Query parameters

ParameterTypeDescription
tenant_idstring

UUID of the tenant (required if not in auth)

Example: {{tenant_id}}

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

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

ParameterTypeDescription
idRequiredstring

UUID of the inventory category to update (required)

Example: category-uuid

Query parameters

ParameterTypeDescription
tenant_idstring

UUID of the tenant (required if not in auth)

Example: {{tenant_id}}

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
nameobject—
name.enstring—
descriptionobject—
description.enstring—
is_activeboolean—
sort_ordernumber—
metadataobject—
metadata.iconstring—
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

ParameterTypeDescription
idRequiredstring

UUID of the inventory category to delete (required)

Example: category-uuid

Query parameters

ParameterTypeDescription
tenant_idstring

UUID of the tenant (required if not in auth)

Example: {{tenant_id}}

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

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}