> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Categories

> Manage product categories with hierarchical structure

## 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.

<ParamField path="name" type="string" required>
  Category name (1-100 characters)
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const categoryId = await convex.mutation(api.shared.categories.createStoreCategory, {
    name: "Specialty Pizzas"
  });
  ```

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

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  "k123456789"
  ```
</ResponseExample>

## Update Store Category

Updates a store-specific category name.

<ParamField path="categoryId" type="Id<'categories'>" required>
  Category ID to update
</ParamField>

<ParamField path="name" type="string" required>
  Updated category name
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const updatedCategory = await convex.mutation(api.shared.categories.updateStoreCategory, {
    categoryId: "k123456789",
    name: "Premium Pizzas"
  });
  ```

  ```javascript JavaScript theme={null}
  const updatedCategory = await convex.mutation("shared.categories.updateStoreCategory", {
    categoryId: "k123456789",
    name: "Premium Pizzas"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "_id": "k123456789",
    "name": "Premium Pizzas",
    "parent": "k987654321",
    "storeId": "j123456789",
    "isActive": true,
    "_creationTime": 1640995200000
  }
  ```
</ResponseExample>

## Delete Store Category

Deletes a store-specific category.

<ParamField path="categoryId" type="Id<'categories'>" required>
  Category ID to delete
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await convex.mutation(api.shared.categories.deleteStoreCategory, {
    categoryId: "k123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const result = await convex.mutation("shared.categories.deleteStoreCategory", {
    categoryId: "k123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true
  }
  ```
</ResponseExample>

## Get Parent Categories

Retrieves all parent categories (categories with no parent).

<CodeGroup>
  ```typescript TypeScript theme={null}
  const categories = await convex.query(api.shared.categories.getParents);
  ```

  ```javascript JavaScript theme={null}
  const categories = await convex.query("shared.categories.getParents");
  ```

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

  categories = response.json()
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_id": "k123456789",
      "name": "Food & Restaurants",
      "parent": null,
      "isActive": true,
      "_creationTime": 1640995200000
    },
    {
      "_id": "k987654321",
      "name": "Electronics",
      "parent": null,
      "isActive": true,
      "_creationTime": 1640995200000
    }
  ]
  ```
</ResponseExample>

## Get Categories by Parent ID

Retrieves all child categories under a parent category.

<ParamField path="parent" type="Id<'categories'>" required>
  Parent category ID
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const childCategories = await convex.query(api.shared.categories.getByParentId, {
    parent: "k123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const childCategories = await convex.query("shared.categories.getByParentId", {
    parent: "k123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_id": "k555555555",
      "name": "Italian Cuisine",
      "parent": "k123456789",
      "isActive": true,
      "_creationTime": 1640995200000
    },
    {
      "_id": "k666666666",
      "name": "Fast Food",
      "parent": "k123456789",
      "isActive": true,
      "_creationTime": 1640995200000
    }
  ]
  ```
</ResponseExample>

## Get Global Categories

Retrieves all global categories (not store-specific).

<CodeGroup>
  ```typescript TypeScript theme={null}
  const globalCategories = await convex.query(api.shared.categories.getGlobalCategories);
  ```

  ```javascript JavaScript theme={null}
  const globalCategories = await convex.query("shared.categories.getGlobalCategories");
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_id": "k123456789",
      "name": "Food & Restaurants",
      "parent": null,
      "isActive": true,
      "isGlobal": true,
      "_creationTime": 1640995200000
    }
  ]
  ```
</ResponseExample>

## Get Store Categories

Retrieves all categories for a specific store.

<ParamField path="storeId" type="Id<'stores'>" required>
  Store ID
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const storeCategories = await convex.query(api.shared.categories.getStoreCategories, {
    storeId: "j123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const storeCategories = await convex.query("shared.categories.getStoreCategories", {
    storeId: "j123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_id": "k777777777",
      "name": "Specialty Pizzas",
      "parent": "k123456789",
      "storeId": "j123456789",
      "isActive": true,
      "_creationTime": 1640995200000
    }
  ]
  ```
</ResponseExample>

## Get Available Categories for Store

Retrieves all categories available to a store (global + store-specific).

<ParamField path="storeId" type="Id<'stores'>" required>
  Store ID
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const availableCategories = await convex.query(api.shared.categories.getAvailableCategoriesForStore, {
    storeId: "j123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const availableCategories = await convex.query("shared.categories.getAvailableCategoriesForStore", {
    storeId: "j123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_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
    }
  ]
  ```
</ResponseExample>

## Category Hierarchy

Categories follow a hierarchical structure:

```mermaid theme={null}
graph TD
    A[Global Categories] --> B[Food & Restaurants]
    A --> C[Electronics]
    A --> D[Fashion]
    
    B --> E[Italian Cuisine]
    B --> F[Fast Food]
    B --> G[Healthy Options]
    
    E --> H[Store: Mario's Pizzas]
    E --> I[Store: Luigi's Kitchen]
    
    H --> J[Specialty Pizzas]
    H --> K[Pasta Dishes]
```

## Error Handling

<AccordionGroup>
  <Accordion title="Category not found">
    **Status Code**: `404`

    ```json theme={null}
    {
      "error": "Category not found or you don't have permission to access it"
    }
    ```
  </Accordion>

  <Accordion title="Duplicate category name">
    **Status Code**: `400`

    ```json theme={null}
    {
      "error": "A category with this name already exists in your store"
    }
    ```
  </Accordion>

  <Accordion title="Cannot delete category with products">
    **Status Code**: `400`

    ```json theme={null}
    {
      "error": "Cannot delete category that contains products. Move or delete products first."
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Hierarchical Organization" icon="sitemap">
    Use the parent-child relationship to create logical product organization that customers can navigate easily.
  </Card>

  <Card title="Naming Convention" icon="tag">
    Use clear, descriptive names that customers will understand. Avoid technical jargon or internal codes.
  </Card>

  <Card title="Global vs Store Categories" icon="store">
    Use global categories for broad classifications and store categories for specific subcategories unique to your store.
  </Card>

  <Card title="Category Maintenance" icon="wrench">
    Regularly review and optimize your category structure based on customer behavior and product performance.
  </Card>
</CardGroup>

<Note>
  Categories are automatically indexed for search functionality. Changes to category names are reflected in search results immediately.
</Note>

<Tip>
  Store-specific categories are automatically created under your store's primary category, ensuring proper hierarchy and organization.
</Tip>