Skip to main content

Category Management

5 API calls in this section.

List Categories​

Storefront & Commerce / Category Management
GET/storefront/categories?flat=false&search=electronics&is_active=true&page=1&limit=20

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 Query Parameters: - flat (optional): Set to 'true' for flat paginated list, 'false' for hierarchical structure (default: false) - search (optional): Search term to find categories by name or description in any language - is_active (optional): Filter by active status (true/false). If not provided, returns all categories - page (optional): Page number for pagination (default: 1, only for flat=true) - limit (optional): Items per page (default: 20, only for flat=true) Authentication Required: Tenant-level access

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/storefront/categories?flat=false&search=electronics&is_active=true&page=1&limit=20" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json"

Query parameters

flatOptional
query string

false

Set to 'true' for flat list, 'false' for hierarchical structure

searchOptional
query string

electronics

Search categories by name or description in any language (en/ar/ku)

is_activeOptional
query string

true

Filter by active status (true/false). If not provided, returns all categories.

pageOptional
query string

1

Page number for pagination (default: 1, only applicable when flat=true)

limitOptional
query string

20

Items per page (default: 20, only applicable when flat=true)

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

JWT token for authenticated requests

Content-TypeOptional
header string

application/json

Responses

Success - Hierarchical Categories200OK
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}
Success - Flat Categories List200OK
Response body
json
1{2  "success": true,3  "categories": [4    {5      "id": "cat-uuid-1",6      "market_id": "market-uuid",7      "parent_id": null,8      "name": {9        "en": "Electronics",10        "ar": "إلكترونيات",11        "ku": "ئەلیکترۆنیات"12      },13      "description": {14        "en": "Electronic devices 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-01T10:00:00Z",22      "children": [23        {24          "id": "cat-uuid-2",25          "market_id": "market-uuid",26          "parent_id": "cat-uuid-1",27          "name": {28            "en": "Smartphones",29            "ar": "الهواتف الذكية",30            "ku": "تەلەفۆنە زیرەکەکان"31          },32          "description": {33            "en": "Mobile phones and accessories",34            "ar": "الهواتف المحمولة والإكسسوارات",35            "ku": "تەلەفۆنی دەستی و پێداویستییەکان"36          },37          "sort_order": 1,38          "is_active": true,39          "created_at": "2023-12-01T10:30:00Z",40          "updated_at": "2023-12-01T10:30:00Z",41          "children": []42        }43      ]44    }45  ]46}
Success - Flat Categories List with Pagination200OK
Response body
json
1{2  "success": true,3  "categories": [4    {5      "id": "cat-uuid-1",6      "market_id": "market-uuid",7      "parent_id": null,8      "name": {9        "en": "Electronics",10        "ar": "إلكترونيات",11        "ku": "ئەلیکترۆنیات"12      },13      "description": {14        "en": "Electronic devices 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-01T10:00:00Z"22    },23    {24      "id": "cat-uuid-2",25      "market_id": "market-uuid",26      "parent_id": "cat-uuid-1",27      "name": {28        "en": "Smartphones",29        "ar": "الهواتف الذكية",30        "ku": "تەلەفۆنە زیرەکەکان"31      },32      "description": {33        "en": "Mobile phones and accessories",34        "ar": "الهواتف المحمولة والإكسسوارات",35        "ku": "تەلەفۆنی دەستی و پێداویستییەکان"36      },37      "sort_order": 1,38      "is_active": true,39      "created_at": "2023-12-01T10:30:00Z",40      "updated_at": "2023-12-01T10:30:00Z"41    }42  ],43  "pagination": {44    "page": 1,45    "limit": 20,46    "total": 2,47    "totalPages": 148  }49}
Error - Unauthorized401Unauthorized
Response body
json
1{2  "success": false,3  "message": "Unauthorized"4}
Error - Market Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Market not found"4}

Get Category​

Storefront & Commerce / Category Management
GET/storefront/categories/:categoryId

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

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/storefront/categories/:categoryId" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

categoryIdRequired
path string

cat-uuid-1

UUID of the category to retrieve

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

JWT token for authenticated requests

Responses

Success - Category Details200OK
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}
Error - Category Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Category not found"4}

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. Request Body Fields: - 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

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/storefront/categories" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "name": {7    "en": "Home & Garden",8    "ar": "المنزل والحديقة",9    "ku": "ماڵ و باخچە"10  },11  "description": {12    "en": "Home improvement and garden supplies",13    "ar": "مستلزمات تحسين المنزل والحديقة",14    "ku": "پێداویستییەکانی باشترکردنی ماڵ و باخچە"15  },16  "category_image": "https://example.com/images/home-garden-category.jpg",17  "parent_id": null,18  "is_active": true,19  "sort_order": 320}'
Request body
json
1{2  "name": {3    "en": "Home & Garden",4    "ar": "المنزل والحديقة",5    "ku": "ماڵ و باخچە"6  },7  "description": {8    "en": "Home improvement and garden supplies",9    "ar": "مستلزمات تحسين المنزل والحديقة",10    "ku": "پێداویستییەکانی باشترکردنی ماڵ و باخچە"11  },12  "category_image": "https://example.com/images/home-garden-category.jpg",13  "parent_id": null,14  "is_active": true,15  "sort_order": 316}

Request body fields

nameExample
object

Example field from the request body.

name.enExample
string

Example field from the request body.

name.arExample
string

Example field from the request body.

name.kuExample
string

Example field from the request body.

descriptionExample
object

Example field from the request body.

description.enExample
string

Example field from the request body.

description.arExample
string

Example field from the request body.

description.kuExample
string

Example field from the request body.

category_imageExample
string

Example field from the request body.

parent_idExample
null

Example field from the request body.

is_activeExample
boolean

Example field from the request body.

sort_orderExample
number

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

JWT token for authenticated requests

Content-TypeOptional
header string

application/json

Responses

Success - Category Created201Created
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}
Success - Subcategory Created201Created
Response body
json
1{2  "success": true,3  "data": {4    "category": {5      "id": "cat-uuid-garden-tools",6      "market_id": "market-uuid",7      "parent_id": "cat-uuid-home-garden",8      "name": {9        "en": "Garden Tools",10        "ar": "أدوات الحديقة",11        "ku": "ئامرازەکانی باخچە"12      },13      "description": {14        "en": "Tools and equipment for gardening",15        "ar": "أدوات ومعدات البستنة",16        "ku": "ئامراز و کەرەستەکانی باخبانی"17      },18      "sort_order": 1,19      "is_active": true,20      "created_at": "2023-12-01T12:30:00Z",21      "updated_at": "2023-12-01T12:30:00Z"22    },23    "message": "Category created successfully"24  }25}
Error - Validation Failed400Bad Request
Response body
json
1{2  "success": false,3  "message": "Validation failed",4  "errors": [5    {6      "field": "name",7      "message": "Field is required"8    }9  ]10}
Error - Unauthorized401Unauthorized
Response body
json
1{2  "success": false,3  "message": "Tenant required"4}

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. Path Parameters: - categoryId (required): UUID of the category to update Request Body Fields (all optional): - 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

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request PUT "$ONDI_BASE_URL/storefront/categories/:categoryId" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "name": {7    "en": "Electronics & Gadgets",8    "ar": "الإلكترونيات والأجهزة",9    "ku": "ئەلیکترۆنیات و ئامێرەکان"10  },11  "description": {12    "en": "Electronic devices, gadgets and accessories",13    "ar": "الأجهزة الإلكترونية والأدوات والإكسسوارات",14    "ku": "ئامێرە ئەلیکترۆنییەکان، ئامێرەکان و پێداویستییەکان"15  },16  "category_image": "https://example.com/images/electronics-gadgets-updated.jpg",17  "is_active": true,18  "sort_order": 119}'
Request body
json
1{2  "name": {3    "en": "Electronics & Gadgets",4    "ar": "الإلكترونيات والأجهزة",5    "ku": "ئەلیکترۆنیات و ئامێرەکان"6  },7  "description": {8    "en": "Electronic devices, gadgets and accessories",9    "ar": "الأجهزة الإلكترونية والأدوات والإكسسوارات",10    "ku": "ئامێرە ئەلیکترۆنییەکان، ئامێرەکان و پێداویستییەکان"11  },12  "category_image": "https://example.com/images/electronics-gadgets-updated.jpg",13  "is_active": true,14  "sort_order": 115}

Path parameters

categoryIdRequired
path string

cat-uuid-1

UUID of the category to update

Request body fields

nameExample
object

Example field from the request body.

name.enExample
string

Example field from the request body.

name.arExample
string

Example field from the request body.

name.kuExample
string

Example field from the request body.

descriptionExample
object

Example field from the request body.

description.enExample
string

Example field from the request body.

description.arExample
string

Example field from the request body.

description.kuExample
string

Example field from the request body.

category_imageExample
string

Example field from the request body.

is_activeExample
boolean

Example field from the request body.

sort_orderExample
number

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

JWT token for authenticated requests

Content-TypeOptional
header string

application/json

Responses

Success - Category Updated200OK
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}
Success - Partial Update200OK
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": false,20      "created_at": "2023-12-01T10:00:00Z",21      "updated_at": "2023-12-01T13:30:00Z"22    },23    "message": "Category updated successfully"24  }25}
Error - Category Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Category not found"4}
Error - Unauthorized401Unauthorized
Response body
json
1{2  "success": false,3  "message": "Tenant required"4}

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. Path Parameters: - 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

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request DELETE "$ONDI_BASE_URL/storefront/categories/:categoryId" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

categoryIdRequired
path string

cat-uuid-1

UUID of the category to delete

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

JWT token for authenticated requests

Responses

Success - Category Deleted200OK
Response body
json
1{2  "success": true,3  "data": {4    "message": "Category deleted successfully"5  }6}
Error - Category Has Children400Bad Request
Response body
json
1{2  "success": false,3  "message": "Category has children and cannot be deleted. Please delete or move child categories first."4}
Error - Category Has Products400Bad Request
Response body
json
1{2  "success": false,3  "message": "Category has products assigned and cannot be deleted. Please reassign or remove products first."4}
Error - Category Not Found404Not Found
Response body
json
1{2  "success": false,3  "message": "Category not found"4}
Error - Unauthorized401Unauthorized
Response body
json
1{2  "success": false,3  "message": "Unauthorized"4}