TWIGZ Backend API Documentation

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"
});

const categoryId = await convex.mutation("shared.categories.createStoreCategory", {
  name: "Specialty Pizzas"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "shared.categories.createStoreCategory",
        "args": {
            "name": "Specialty Pizzas"
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

category_id = response.json()

"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"
});

const updatedCategory = await convex.mutation("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"
});

const result = await convex.mutation("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);

const categories = await convex.query("shared.categories.getParents");

response = requests.post(
    f"{CONVEX_URL}/api/query",
    json={
        "path": "shared.categories.getParents",
        "args": {}
    },
    headers={"Authorization": f"Bearer {token}"}
)

categories = response.json()

[
  {
    "_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"
});

const childCategories = await convex.query("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);

const globalCategories = await convex.query("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"
});

const storeCategories = await convex.query("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"
});

const availableCategories = await convex.query("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

Category not found

Status Code: 404

{
  "error": "Category not found or you don't have permission to access it"
}

Duplicate category name

Status Code: 400

{
  "error": "A category with this name already exists in your store"
}

Cannot delete category with products

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.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Categories

Overview

Create Store Category

Update Store Category

Delete Store Category

Get Parent Categories

Get Categories by Parent ID

Get Global Categories

Get Store Categories

Get Available Categories for Store

Category Hierarchy

Error Handling

Best Practices

Hierarchical Organization

Naming Convention

Global vs Store Categories

Category Maintenance

​Overview

​Create Store Category

​Update Store Category

​Delete Store Category

​Get Parent Categories

​Get Categories by Parent ID

​Get Global Categories

​Get Store Categories

​Get Available Categories for Store

​Category Hierarchy

​Error Handling

​Best Practices

Hierarchical Organization

Naming Convention

Global vs Store Categories

Category Maintenance

Overview

Create Store Category

Update Store Category

Delete Store Category

Get Parent Categories

Get Categories by Parent ID

Get Global Categories

Get Store Categories

Get Available Categories for Store

Category Hierarchy

Error Handling

Best Practices