How to Categorize Products for Commercetools

Understanding Commercetools Product Categorization

Commercetools has established itself as the leading cloud-native, headless commerce platform built on MACH principles (Microservices, API-first, Cloud-native, Headless). Trusted by innovative brands worldwide for its unmatched flexibility and scalability, Commercetools enables enterprises to build composable commerce experiences that adapt rapidly to changing market demands. Product categorization within this API-first ecosystem requires understanding the platform's unique approach to catalog management, where categories are first-class citizens in a GraphQL and REST API landscape. Our AI-powered categorization API is designed specifically for the Commercetools architecture, delivering low-latency category predictions that integrate seamlessly with your headless commerce implementation.

The Commercetools platform implements a flexible category model that supports hierarchical structures with unlimited nesting depth, localized names and descriptions across multiple languages, and sophisticated ordering and visibility controls. Categories in Commercetools are defined independently from products, allowing the same category structure to be reused across multiple stores or projects within your Commercetools organization. Products reference categories through category assignments that can include order hints for controlling product sort order within category listings. This separation of concerns between categories and products aligns with composable commerce principles, enabling independent management and evolution of your taxonomy and product catalog.

Commercetools' API-first architecture means that all category and product operations are performed through well-documented REST and GraphQL APIs, making integration with AI-powered categorization services straightforward and flexible. Whether you're building product import pipelines, catalog management interfaces, or real-time categorization during content authoring, our API complements Commercetools' native capabilities by providing intelligent category suggestions based on product attributes, descriptions, and contextual information. The system respects Commercetools' category key and ID structure, returning predictions that can be directly applied through the Commercetools API without translation or mapping overhead.

The platform's multi-store capabilities allow enterprises to operate multiple distinct commerce experiences from a single Commercetools project, each potentially with different category structures, product assortments, and localized content. Our categorization API supports store-aware predictions, understanding that the same physical product might require different category assignments depending on the store context, customer segment, or geographic market. This flexibility is essential for global brands managing diverse commerce operations through Commercetools' unified platform, ensuring that AI-powered categorization enhances rather than constrains your composable commerce architecture.

Commercetools Category Architecture

Commercetools implements a modern, API-native category system designed for the requirements of headless and composable commerce architectures. Understanding this architecture is essential for effective AI-powered categorization that respects the platform's data model, leverages its flexibility, and integrates seamlessly with your Commercetools implementation. The platform's approach to categories emphasizes API accessibility, localization support, and the separation of category definitions from product associations.

Categories in Commercetools are identified by both system-generated IDs and optional human-readable keys that you define. The key-based identification system is particularly valuable for integrations because it provides stable, meaningful identifiers that remain consistent across environments and don't require ID translation between development, staging, and production projects. Our AI categorization API can return predictions using either ID or key references, depending on your integration pattern preferences, enabling direct category assignment without additional lookup operations.

The platform supports rich category metadata including localized names, descriptions, and slugs for SEO-friendly URLs, along with custom fields for extending category data with business-specific attributes. Category hierarchies are defined through parent references, creating tree structures that can be traversed efficiently through the API. Products can belong to multiple categories simultaneously, with optional order hints that control product positioning within category listings. This multi-category capability, combined with Commercetools' faceted search features, enables sophisticated product discovery experiences that our categorization API enhances by suggesting optimal category placements.

Common Composable Commerce Categories

Commercetools' flexibility allows brands to define custom category structures that precisely match their business requirements and customer navigation patterns. Our AI models are trained to recognize and adapt to custom taxonomies, learning from your existing categorized products to provide predictions that align with your established organizational patterns. This is particularly important for brands with unique category structures that reflect their specific merchandising strategies or industry conventions.

API Integration Guide

Integrating our product categorization API with your Commercetools implementation is straightforward and aligns with the platform's API-first philosophy. Whether you're building Node.js microservices, serverless functions, or full-stack applications, our RESTful API endpoints provide consistent, low-latency categorization services that complement Commercetools' native capabilities and respect your MACH architecture principles.

import { createApiBuilderFromCtpClient } from '@commercetools/platform-sdk';

interface CategorizationResult {
    categoryKey: string;
    categoryPath: string;
    confidence: number;
    localizedName: Record;
}

async function categorizeForCommercetools(
    productName: string,
    description: string,
    apiKey: string
): Promise {
    const baseUrl = 'https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php';
    const query = encodeURIComponent(`${productName} ${description}`);

    const response = await fetch(
        `${baseUrl}?query=${query}&api_key=${apiKey}&data_type=commercetools`
    );
    const result = await response.json();

    return {
        categoryKey: result.category_key,
        categoryPath: result.category,
        confidence: result.confidence,
        localizedName: result.localized_names
    };
}

// Example: Categorize and assign to Commercetools product
const result = await categorizeForCommercetools(
    'Nike Air Max 270 React',
    'Premium running shoes with React foam cushioning',
    'your_api_key'
);

// Use with Commercetools SDK to add category
const updateAction = {
    action: 'addToCategory',
    category: { key: result.categoryKey, typeId: 'category' }
};

import requests
from commercetools import Client

def categorize_for_commercetools(product_data: dict, api_key: str) -> dict:
    """
    Categorize a product for Commercetools
    Returns category key and localized names
    """
    base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php"

    query = f"{product_data['name']['en']} {product_data.get('description', {}).get('en', '')}"

    params = {
        "query": query,
        "api_key": api_key,
        "data_type": "commercetools"
    }

    response = requests.get(base_url, params=params)
    result = response.json()

    return {
        "category_key": result['category_key'],
        "category_path": result['category'],
        "confidence": result.get('confidence', 0.95),
        "localized_names": result.get('localized_names', {})
    }

# Example usage
product = {
    "name": {"en": "Wireless Bluetooth Headphones", "de": "Kabellose Bluetooth-Kopfhörer"},
    "description": {"en": "Premium noise-cancelling headphones with 30-hour battery"}
}

result = categorize_for_commercetools(product, "your_api_key")
print(f"Category: {result['category_key']}")

curl -X GET "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php" \
  -d "query=Patagonia Down Sweater Jacket Recycled Materials Outdoor" \
  -d "api_key=your_api_key_here" \
  -d "data_type=commercetools"