Category Management

5 API calls in this section.

List Categories

Storefront & Commerce / Category Management

GET/storefront/categories

Retrieves categories for the authenticated tenant's market with search and filtering capabilities. By default returns hierarchical structure with parent-child relationships. Use ?flat=true for a paginated flat list.

Features

• Market-scoped (only shows categories for current tenant)

• Multi-language support (en/ar/ku)

• Hierarchical organization with search/filter support

• Advanced search in category names and descriptions

• Active/inactive status filtering

• Pagination support for flat lists

• Ordered by sort_order field

Search & Filter Features

• Multi-language Search: Searches across English, Arabic, and Kurdish category names and descriptions

• Status Filtering: Filter by active/inactive categories

• Pagination: Available for flat list view only

• Hierarchical Filtering: Search and status filters apply to hierarchical view as well

Authentication Required

Tenant-level access

Query parameters

Parameter	Type	Description
flatOptional	string	Set to 'true' for flat list, 'false' for hierarchical structure Set to 'true' for flat paginated list, 'false' for hierarchical structure (default: false) Set to 'true' for flat list, 'false' for hierarchical structure Set to 'true' for flat paginated list, 'false' for hierarchical structure (default: false) Example: false
searchOptional	string	Search categories by name or description in any language (en/ar/ku) Search term to find categories by name or description in any language Search categories by name or description in any language (en/ar/ku) Search term to find categories by name or description in any language Example: electronics
is_activeOptional	string	Filter by active status (true/false). If not provided, returns all categories. Filter by active status (true/false). If not provided, returns all categories. Example: true
pageOptional	string	Page number for pagination (default: 1, only applicable when flat=true) Page number for pagination (default: 1, only for flat=true) Page number for pagination (default: 1, only applicable when flat=true) Page number for pagination (default: 1, only for flat=true) Example: 1
limitOptional	string	Items per page (default: 20, only applicable when flat=true) Items per page (default: 20, only for flat=true) Items per page (default: 20, only applicable when flat=true) Items per page (default: 20, only for flat=true) Example: 20

Headers

Parameter	Type	Description
Authorization	string	JWT token for authenticated requests JWT token for authenticated requests Example: Bearer {{access_token}}
Content-Type	string	Example: application/json

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/categories?flat=false&search=electronics&is_active=true&page=1&limit=20" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json"

Response examples

200 · Success - Hierarchical Categories200 · Success - Flat Categories List200 · Success - Flat Categories List with Pagination401 · Error - Unauthorized404 · Error - Market Not Found

200OK

Response body

json

1{2  "success": true,3  "data": {4    "categories": [5      {6        "id": "cat-uuid-1",7        "market_id": "market-uuid",8        "parent_id": null,9        "name": {10          "en": "Electronics",11          "ar": "إلكترونيات",12          "ku": "ئەلیکترۆنیات"13        },14        "description": {15          "en": "Electronic devices and accessories",16          "ar": "الأجهزة الإلكترونية والإكسسوارات",17          "ku": "ئامێرە ئەلیکترۆنییەکان و پێداویستییەکان"18        },19        "category_image": "https://example.com/images/electronics-category.jpg",20        "sort_order": 1,21        "is_active": true,22        "created_at": "2023-12-01T10:00:00Z",23        "updated_at": "2023-12-01T10:00:00Z",24        "children": [25          {26            "id": "cat-uuid-2",27            "market_id": "market-uuid",28            "parent_id": "cat-uuid-1",29            "name": {30              "en": "Smartphones",31              "ar": "الهواتف الذكية",32              "ku": "تەلەفۆنە زیرەکەکان"33            },34            "description": {35              "en": "Mobile phones and accessories",36              "ar": "الهواتف المحمولة والإكسسوارات",37              "ku": "تەلەفۆنی دەستی و پێداویستییەکان"38            },39            "category_image": "https://example.com/images/smartphones-category.jpg",40            "sort_order": 1,41            "is_active": true,42            "created_at": "2023-12-01T10:30:00Z",43            "updated_at": "2023-12-01T10:30:00Z",44            "children": []45          }46        ]47      },48      {49        "id": "cat-uuid-3",50        "market_id": "market-uuid",51        "parent_id": null,52        "name": {53          "en": "Clothing",54          "ar": "ملابس",55          "ku": "جل و بەرگ"56        },57        "description": {58          "en": "Apparel and fashion items",59          "ar": "ملابس وأزياء",60          "ku": "جل و بەرگ و مۆدە"61        },62        "category_image": "https://example.com/images/clothing-category.jpg",63        "sort_order": 2,64        "is_active": true,65        "created_at": "2023-12-01T11:00:00Z",66        "updated_at": "2023-12-01T11:00:00Z",67        "children": []68      }69    ]70  }71}

Get Category

Storefront & Commerce / Category Management

GET/storefront/categories/:categoryId

Retrieves a single category by its ID for the authenticated tenant's market.

Path parameters

Parameter	Type	Description
categoryIdRequired	string	UUID of the category to retrieve UUID of the category to retrieve Example: cat-uuid-1

Headers

Parameter	Type	Description
Authorization	string	JWT token for authenticated requests JWT token for authenticated requests Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/storefront/categories/${CATEGORYID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Category Details404 · Error - Category Not Found

200OK

Response body

json

1{2  "success": true,3  "data": {4    "id": "cat-uuid-1",5    "market_id": "market-uuid",6    "parent_id": null,7    "name": {8      "en": "Electronics",9      "ar": "إلكترونيات",10      "ku": "ئەلیکترۆنیات"11    },12    "description": {13      "en": "Electronic devices and accessories",14      "ar": "الأجهزة الإلكترونية والإكسسوارات",15      "ku": "ئامێرە ئەلیکترۆنییەکان و پێداویستییەکان"16    },17    "sort_order": 1,18    "is_active": true,19    "created_at": "2023-12-01T10:00:00Z",20    "updated_at": "2023-12-01T10:00:00Z"21  }22}

Create Category

Storefront & Commerce / Category Management

POST/storefront/categories

Creates a new category in the authenticated tenant's market. Categories can be organized hierarchically by setting a parent_id and can include visual representation with category images.

• name (required): Multi-language object with category names

• description (optional): Multi-language object with category descriptions

• category_image (optional): URL or path to category image for visual representation

• parent_id (optional): UUID of parent category for hierarchical organization

• is_active (optional): Boolean to set category status (default: true)

• sort_order (optional): Integer for display ordering (default: 0)

Features

• Multi-language support (en/ar/ku)

• Visual category representation with images

• Hierarchical categorization

• Custom sorting order

• Active/inactive status control

• Market-scoped creation

Image Recommendations

• Use high-quality images that represent the category

• Recommended size: 400x400 pixels or larger

• Supported formats: JPG, PNG, WebP

• Store images in accessible URLs (CDN recommended)

Authentication Required

Tenant-level access

Headers

Parameter	Type	Description
Authorization	string	JWT token for authenticated requests JWT token for authenticated requests 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	—
description.ar	string	—
description.ku	string	—
category_image	string	—
parent_id	null	—
is_active	boolean	—
sort_order	number	—

Staging

Request

curl

1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/storefront/categories" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": {6    "en": "Home & Garden",7    "ar": "المنزل والحديقة",8    "ku": "ماڵ و باخچە"9  },10  "description": {11    "en": "Home improvement and garden supplies",12    "ar": "مستلزمات تحسين المنزل والحديقة",13    "ku": "پێداویستییەکانی باشترکردنی ماڵ و باخچە"14  },15  "category_image": "https://example.com/images/home-garden-category.jpg",16  "parent_id": null,17  "is_active": true,18  "sort_order": 319}'

Response examples

201 · Success - Category Created201 · Success - Subcategory Created400 · Error - Validation Failed401 · Error - Unauthorized

201Created

Response body

json

1{2  "success": true,3  "data": {4    "category": {5      "id": "cat-uuid-new",6      "market_id": "market-uuid",7      "parent_id": null,8      "name": {9        "en": "Home & Garden",10        "ar": "المنزل والحديقة",11        "ku": "ماڵ و باخچە"12      },13      "description": {14        "en": "Home improvement and garden supplies",15        "ar": "مستلزمات تحسين المنزل والحديقة",16        "ku": "پێداویستییەکانی باشترکردنی ماڵ و باخچە"17      },18      "category_image": "https://example.com/images/home-garden-category.jpg",19      "sort_order": 3,20      "is_active": true,21      "created_at": "2023-12-01T12:00:00Z",22      "updated_at": "2023-12-01T12:00:00Z"23    },24    "message": "Category created successfully"25  }26}

Update Category

Storefront & Commerce / Category Management

PUT/storefront/categories/:categoryId

Updates an existing category in the authenticated tenant's market. All fields are optional for partial updates including the category image.

• categoryId (required): UUID of the category to update

• name: Multi-language object with updated category names

• description: Multi-language object with updated category descriptions

• category_image: URL or path to updated category image

• parent_id: UUID of new parent category (null to make root category)

• is_active: Boolean to update category status

• sort_order: Integer for updated display ordering

Features

• Partial updates (only provided fields are updated)

• Multi-language support

• Image updates for visual representation

• Hierarchical reorganization

• Status and ordering updates

• Market-scoped updates

Image Update Notes

• Provide new image URL to update category image

• Set to null to remove existing image

• Same image recommendations as creation apply

Authentication Required

Tenant-level access

Path parameters

Parameter	Type	Description
categoryIdRequired	string	UUID of the category to update UUID of the category to update Example: cat-uuid-1

Headers

Parameter	Type	Description
Authorization	string	JWT token for authenticated requests JWT token for authenticated requests 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	—
description.ar	string	—
description.ku	string	—
category_image	string	—
is_active	boolean	—
sort_order	number	—

Staging

Request

curl

1curl --globoff --request PUT "https://staging-api.ondi.io/functions/v1/storefront/categories/${CATEGORYID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "name": {6    "en": "Electronics & Gadgets",7    "ar": "الإلكترونيات والأجهزة",8    "ku": "ئەلیکترۆنیات و ئامێرەکان"9  },10  "description": {11    "en": "Electronic devices, gadgets and accessories",12    "ar": "الأجهزة الإلكترونية والأدوات والإكسسوارات",13    "ku": "ئامێرە ئەلیکترۆنییەکان، ئامێرەکان و پێداویستییەکان"14  },15  "category_image": "https://example.com/images/electronics-gadgets-updated.jpg",16  "is_active": true,17  "sort_order": 118}'

Response examples

200 · Success - Category Updated200 · Success - Partial Update404 · Error - Category Not Found401 · Error - Unauthorized

200OK

Response body

json

1{2  "success": true,3  "data": {4    "category": {5      "id": "cat-uuid-1",6      "market_id": "market-uuid",7      "parent_id": null,8      "name": {9        "en": "Electronics & Gadgets",10        "ar": "الإلكترونيات والأجهزة",11        "ku": "ئەلیکترۆنیات و ئامێرەکان"12      },13      "description": {14        "en": "Electronic devices, gadgets and accessories",15        "ar": "الأجهزة الإلكترونية والأدوات والإكسسوارات",16        "ku": "ئامێرە ئەلیکترۆنییەکان، ئامێرەکان و پێداویستییەکان"17      },18      "sort_order": 1,19      "is_active": true,20      "created_at": "2023-12-01T10:00:00Z",21      "updated_at": "2023-12-01T13:00:00Z"22    },23    "message": "Category updated successfully"24  }25}

Delete Category

Storefront & Commerce / Category Management

DELETE/storefront/categories/:categoryId

Deletes a category from the authenticated tenant's market. Includes safety checks to prevent data loss.

• categoryId (required): UUID of the category to delete

Safety Features

• Cannot delete category if it has child categories

• Cannot delete category if it has assigned products

• Returns specific error messages for each prevention case

• Market-scoped deletion (only within tenant's market)

Deletion Rules

1. Category must exist and belong to the tenant's market

2. Category must not have any child categories

3. Category must not have any assigned products

4. If any rule fails, deletion is prevented with explanation

Authentication Required

Tenant-level access

Path parameters

Parameter	Type	Description
categoryIdRequired	string	UUID of the category to delete UUID of the category to delete Example: cat-uuid-1

Headers

Parameter	Type	Description
Authorization	string	JWT token for authenticated requests JWT token for authenticated requests Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request DELETE "https://staging-api.ondi.io/functions/v1/storefront/categories/${CATEGORYID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Category Deleted400 · Error - Category Has Children400 · Error - Category Has Products404 · Error - Category Not Found401 · Error - Unauthorized

200OK

Response body

json

1{2  "success": true,3  "data": {4    "message": "Category deleted successfully"5  }6}