Categories & Subcategories

Access product categories and subcategories to organize and filter products effectively.

Get all product categories available in the system.

Endpoint

GET /api/v1/categories

Authentication: Bearer token required

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50)
page	number	No	Page number to retrieve (default: 1)
include_subcategories	boolean	No	Include subcategories in response (default: false)
active_only	boolean	No	Only return active categories (default: true)

Response

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Page: 1
X-Per-Page: 50
X-Total-Count: 15
X-Total-Pages: 1
X-Page-Size: 3
X-Has-More: false

Response Body

[
  {
    "id": 1,
    "name": "Gift Cards",
    "slug": "gift-cards",
    "description": "Digital and physical gift cards for retail stores",
    "icon": "gift-card",
    "is_active": true,
    "product_count": 1247,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  {
    "id": 2,
    "name": "Mobile Top-up",
    "slug": "mobile-topup",
    "description": "Mobile phone credit and data plans",
    "icon": "mobile",
    "is_active": true,
    "product_count": 856,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  {
    "id": 3,
    "name": "Digital Services",
    "slug": "digital-services",
    "description": "Online services and subscriptions",
    "icon": "cloud",
    "is_active": true,
    "product_count": 342,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
]

Category Object

Field	Type	Description
id	number	Unique category identifier
name	string	Category display name
slug	string	URL-friendly category identifier
description	string	Category description
icon	string	Icon identifier for UI
is_active	boolean	Whether category is currently active
product_count	number	Number of products in this category
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

With Subcategories

[
  {
    "id": 1,
    "name": "Gift Cards",
    "slug": "gift-cards",
    "description": "Digital and physical gift cards for retail stores",
    "icon": "gift-card",
    "is_active": true,
    "product_count": 1247,
    "subcategories": [
      {
        "id": 101,
        "name": "Retail Stores",
        "slug": "retail-stores",
        "description": "Gift cards for department stores and retailers",
        "product_count": 523,
        "is_active": true
      },
      {
        "id": 102,
        "name": "Restaurants",
        "slug": "restaurants",
        "description": "Gift cards for dining and food delivery",
        "product_count": 287,
        "is_active": true
      }
    ],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
]

Examples

# Get all categories
curl -X GET "{{host}}/api/v1/categories" \
  -H "Authorization: Bearer your_access_token"

# Get categories with subcategories
curl -X GET "{{host}}/api/v1/categories?include_subcategories=true" \
  -H "Authorization: Bearer your_access_token"

List Subcategories

Get all subcategories, optionally filtered by parent category.

Endpoint

GET /api/v1/subcategories

Authentication: Bearer token required

Query Parameters

Parameter	Type	Required	Description
category_id	number	No	Filter by parent category ID
limit	number	No	Number of results per page (default: 50)
page	number	No	Page number to retrieve (default: 1)
active_only	boolean	No	Only return active subcategories (default: true)

Response

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Page: 1
X-Per-Page: 50
X-Total-Count: 47
X-Total-Pages: 1
X-Page-Size: 2
X-Has-More: true

Response Body

[
  {
    "id": 101,
    "category_id": 1,
    "name": "Retail Stores",
    "slug": "retail-stores",
    "description": "Gift cards for department stores and retailers",
    "is_active": true,
    "product_count": 523,
    "category": {
      "id": 1,
      "name": "Gift Cards",
      "slug": "gift-cards"
    },
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  {
    "id": 102,
    "category_id": 1,
    "name": "Restaurants",
    "slug": "restaurants",
    "description": "Gift cards for dining and food delivery",
    "is_active": true,
    "product_count": 287,
    "category": {
      "id": 1,
      "name": "Gift Cards",
      "slug": "gift-cards"
    },
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
]

Subcategory Object

Field	Type	Description
id	number	Unique subcategory identifier
category_id	number	Parent category ID
name	string	Subcategory display name
slug	string	URL-friendly subcategory identifier
description	string	Subcategory description
is_active	boolean	Whether subcategory is currently active
product_count	number	Number of products in this subcategory
category	object	Parent category information
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Examples

# Get all subcategories
curl -X GET "{{host}}/api/v1/subcategories" \
  -H "Authorization: Bearer your_access_token"

# Get subcategories for a specific category
curl -X GET "{{host}}/api/v1/subcategories?category_id=1" \
  -H "Authorization: Bearer your_access_token"

React Component Example

import { useState, useEffect } from 'react';

function CategoryNav() {
  const [categories, setCategories] = useState([]);
  const [selectedCategory, setSelectedCategory] = useState(null);
  const [selectedSubcategory, setSelectedSubcategory] = useState(null);

  useEffect(() => {
    const loadCategories = async () => {
      const result = await getCategories(true);
      setCategories(result.data);
    };
    loadCategories();
  }, []);

  const handleCategorySelect = (category) => {
    setSelectedCategory(category);
    setSelectedSubcategory(null);
  };

  const handleSubcategorySelect = (subcategory) => {
    setSelectedSubcategory(subcategory);
  };

  return (
    <div className="category-nav">
      <div className="categories">
        {categories.map(category => (
          <div key={category.id} className="category-item">
            <button
              className={`category-btn ${selectedCategory?.id === category.id ? 'active' : ''}`}
              onClick={() => handleCategorySelect(category)}
            >
              <span className={`icon ${category.icon}`}></span>
              {category.name}
              <span className="count">({category.product_count})</span>
            </button>

            {selectedCategory?.id === category.id && category.subcategories?.length > 0 && (
              <div className="subcategories">
                {category.subcategories.map(subcategory => (
                  <button
                    key={subcategory.id}
                    className={`subcategory-btn ${selectedSubcategory?.id === subcategory.id ? 'active' : ''}`}
                    onClick={() => handleSubcategorySelect(subcategory)}
                  >
                    {subcategory.name}
                    <span className="count">({subcategory.product_count})</span>
                  </button>
                ))}
              </div>
            )}
          </div>
        ))}
      </div>

      {selectedCategory && (
        <div className="breadcrumb">
          <span>{selectedCategory.name}</span>
          {selectedSubcategory && (
            <>
              <span className="separator">/</span>
              <span>{selectedSubcategory.name}</span>
            </>
          )}
        </div>
      )}
    </div>
  );
}

Search and Filter

// Filter products by category and subcategory
const filterProductsByCategory = async (categoryId, subcategoryId = null) => {
  const params = new URLSearchParams({
    category_id: categoryId
  });

  if (subcategoryId) {
    params.append('subcategory_id', subcategoryId);
  }

  const response = await fetch(
    `{{host}}/api/v1/products?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  return response.json();
};

// Build category filters for search
const buildCategoryFilters = (categories) => {
  return categories.reduce((filters, category) => {
    filters[category.slug] = {
      id: category.id,
      name: category.name,
      subcategories: (category.subcategories || []).reduce((subFilters, sub) => {
        subFilters[sub.slug] = {
          id: sub.id,
          name: sub.name
        };
        return subFilters;
      }, {})
    };
    return filters;
  }, {});
};

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

404 Not Found

{
  "error": "Not Found",
  "message": "Category not found"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Use Cases

Build hierarchical navigation menus
Create category-based filtering systems
Generate breadcrumb navigation

Analytics and Reporting

Track popular categories and subcategories
Monitor product distribution across categories
Generate category-based sales reports

Admin Management

Manage product categorization
Update category metadata
Monitor category performance

Next Steps

Explore Products to see how categories are used
Learn about filtering products by category in the products API
Use categories to organize and search your product catalog

Categories & Subcategories

Categories & Subcategories

Endpoint

Query Parameters

Response

Response Headers

Response Body

Category Object

With Subcategories

Examples

List Subcategories

Endpoint

Query Parameters

Response

Response Headers

Response Body

Subcategory Object

Examples

Category Navigation UI

React Component Example

Search and Filter

Error Responses

401 Unauthorized

404 Not Found

500 Internal Server Error

Use Cases

Product Catalog Navigation

Analytics and Reporting

Admin Management

Next Steps

On this page