Skip to main content

​
Overview

The Categories API provides comprehensive category management for organizing products in your marketplace. It supports both global categories (available to all stores) and store-specific categories, creating a flexible hierarchical structure. Location: convex/shared/categories.ts

​
Create Store Category

Creates a new store-specific category under the store’s primary category.
​
name
string
required
Category name (1-100 characters)
const categoryId = await convex.mutation(api.shared.categories.createStoreCategory, {
  name: "Specialty Pizzas"
});

"k123456789"

​
Update Store Category

Updates a store-specific category name.
​
categoryId
Id<'categories'>
required
Category ID to update
​
name
string
required
Updated category name
const updatedCategory = await convex.mutation(api.shared.categories.updateStoreCategory, {
  categoryId: "k123456789",
  name: "Premium Pizzas"
});

{
  "_id": "k123456789",
  "name": "Premium Pizzas",
  "parent": "k987654321",
  "storeId": "j123456789",
  "isActive": true,
  "_creationTime": 1640995200000
}

​
Delete Store Category

Deletes a store-specific category.
​
categoryId
Id<'categories'>
required
Category ID to delete
const result = await convex.mutation(api.shared.categories.deleteStoreCategory, {
  categoryId: "k123456789"
});

{
  "success": true
}

​
Get Parent Categories

Retrieves all parent categories (categories with no parent). 
const categories = await convex.query(api.shared.categories.getParents);

[
  {
    "_id": "k123456789",
    "name": "Food & Restaurants",
    "parent": null,
    "isActive": true,
    "_creationTime": 1640995200000
  },
  {
    "_id": "k987654321",
    "name": "Electronics",
    "parent": null,
    "isActive": true,
    "_creationTime": 1640995200000
  }
]

​
Get Categories by Parent ID

Retrieves all child categories under a parent category.
​
parent
Id<'categories'>
required
Parent category ID
const childCategories = await convex.query(api.shared.categories.getByParentId, {
  parent: "k123456789"
});

[
  {
    "_id": "k555555555",
    "name": "Italian Cuisine",
    "parent": "k123456789",
    "isActive": true,
    "_creationTime": 1640995200000
  },
  {
    "_id": "k666666666",
    "name": "Fast Food",
    "parent": "k123456789",
    "isActive": true,
    "_creationTime": 1640995200000
  }
]

​
Get Global Categories

Retrieves all global categories (not store-specific). 
const globalCategories = await convex.query(api.shared.categories.getGlobalCategories);

[
  {
    "_id": "k123456789",
    "name": "Food & Restaurants",
    "parent": null,
    "isActive": true,
    "isGlobal": true,
    "_creationTime": 1640995200000
  }
]

​
Get Store Categories

Retrieves all categories for a specific store.
​
storeId
Id<'stores'>
required
Store ID
const storeCategories = await convex.query(api.shared.categories.getStoreCategories, {
  storeId: "j123456789"
});

[
  {
    "_id": "k777777777",
    "name": "Specialty Pizzas",
    "parent": "k123456789",
    "storeId": "j123456789",
    "isActive": true,
    "_creationTime": 1640995200000
  }
]

​
Get Available Categories for Store

Retrieves all categories available to a store (global + store-specific).
​
storeId
Id<'stores'>
required
Store ID
const availableCategories = await convex.query(api.shared.categories.getAvailableCategoriesForStore, {
  storeId: "j123456789"
});

[
  {
    "_id": "k123456789",
    "name": "Food & Restaurants",
    "parent": null,
    "isActive": true,
    "isGlobal": true,
    "_creationTime": 1640995200000
  },
  {
    "_id": "k777777777",
    "name": "Specialty Pizzas",
    "parent": "k123456789",
    "storeId": "j123456789",
    "isActive": true,
    "isGlobal": false,
    "_creationTime": 1640995200000
  }
]

​
Category Hierarchy

Categories follow a hierarchical structure:

​
Error Handling

Status Code: 404
{
  "error": "Category not found or you don't have permission to access it"
}
Status Code: 400
{
  "error": "A category with this name already exists in your store"
}
Status Code: 400
{
  "error": "Cannot delete category that contains products. Move or delete products first."
}

​
Best Practices

Hierarchical Organization

Use the parent-child relationship to create logical product organization that customers can navigate easily.

Naming Convention

Use clear, descriptive names that customers will understand. Avoid technical jargon or internal codes.

Global vs Store Categories

Use global categories for broad classifications and store categories for specific subcategories unique to your store.

Category Maintenance

Regularly review and optimize your category structure based on customer behavior and product performance.
Categories are automatically indexed for search functionality. Changes to category names are reflected in search results immediately.
Store-specific categories are automatically created under your store’s primary category, ensuring proper hierarchy and organization.