Categories

Categories organize your product catalog into a hierarchical tree. Each category can have a parent, forming nested paths like Electronics > Phones > Smartphones. Products can be assigned to any category at any level.

The Category Object

{
  "id": "cat_abc123",
  "category_code": "CAT-PHONES",
  "organization_id": "org_abc123",
  "name_en": "Smartphones",
  "name_ar": "هواتف ذكية",
  "parent_id": "cat_electronics",
  "depth": 2,
  "path": "Electronics > Phones > Smartphones",
  "product_count": 150,
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:22:00Z"
}

Fields

Field	Type	Description
`id`	string	Internal Linkit ID
`category_code`	string	Your unique identifier
`name_en`	string	Category name in English
`name_ar`	string	Category name in Arabic
`parent_id`	string	Parent category ID (null for root)
`depth`	integer	Nesting level (0 = root)
`path`	string	Full breadcrumb path
`product_count`	integer	Number of products in this category

GET /api/v1/categories

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`parent_id`	string	-	Filter by parent (use `null` for root categories)
`search`	string	-	Search in category names

Example Request

curl -X GET "https://linkit.works/api/v1/categories?parent_id=null&limit=50" \
  -H "Authorization: Bearer your_token_here"

const response = await fetch(
  'https://linkit.works/api/v1/categories?parent_id=null&limit=50',
  { headers: { 'Authorization': 'Bearer your_token_here' } }
);
const categories = await response.json();

import requests

response = requests.get(
    'https://linkit.works/api/v1/categories',
    params={'parent_id': 'null', 'limit': 50},
    headers={'Authorization': 'Bearer your_token_here'}
)
categories = response.json()

Get Single Category

GET /api/v1/categories/code/{categoryCode}

Returns the full category object including path and product count.

Create Category

POST /api/v1/categories

Request Body

{
  "category_code": "CAT-NEW",
  "name_en": "New Category",
  "name_ar": "فئة جديدة",
  "parent_id": "cat_parent123"
}

Required Fields

Field	Type	Constraints
`category_code`	string	Max 50 chars, unique per organization

Optional Fields

Field	Type	Constraints
`name_en`	string	Max 255 chars
`name_ar`	string	Max 255 chars
`parent_id`	string	Must reference existing category

Setting parent_id places this category as a child. Depth and path are computed automatically.

Response (201 Created)

{
  "success": true,
  "message": "Category created successfully",
  "data": {
    "id": "cat_new123",
    "category_code": "CAT-NEW",
    "depth": 1,
    "path": "Parent > New Category"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Update Category

PUT /api/v1/categories/code/{categoryCode}

Full replacement. Include all fields you want to keep.

Move Category

Change a category's parent, which recalculates depth and path for it and all descendants.

PATCH /api/v1/categories/code/{categoryCode}/move

Request Body

{
  "new_parent_id": "cat_other_parent"
}

Set new_parent_id to null to make the category a root node.

Circular reference protection

You cannot move a category under one of its own descendants. The API returns 409 Conflict if this is attempted.

Delete Category

DELETE /api/v1/categories/code/{categoryCode}

Parameter	Type	Default	Description
`force`	boolean	false	Delete even if it has sub-categories or products

Deletion behavior

By default, categories with children or associated products cannot be deleted. With force=true, child categories are re-parented to the deleted category's parent, and products are unassigned.

Error Responses

409 Conflict (Has Children)

{
  "code": 409,
  "error": "Category has sub-categories",
  "details": { "child_count": 5, "hint": "Use force=true to delete anyway" }
}

409 Conflict (Circular Reference)

{
  "code": 409,
  "error": "Circular reference detected",
  "details": { "category_code": "CAT-001", "target_parent": "CAT-003" }
}

Products

Assign products to categories.

Brands

Brand management alongside categories.

Categories

Products

Brands

On this page