Skip to content

Fetch Categories

Categories follow a three-level hierarchy (L1 → L2 → L3) in Fynd Commerce to organize products and enhance discoverability across your catalog. Each level serves a distinct purpose:

  • L1: Top-level categories
  • L2: Sub-categories that group related products
  • L3: Leaf categories representing the most specific product classification
Category Workflow

Categories are sales-channel specific, meaning L1 and L2 remain consistent across channels, while L3 names can be customized per channel to meet marketplace-specific requirements or unique business needs.

The Fetch Categories endpoint retrieves the complete category hierarchy configured for your company. Use this API to access category metadata (including IDs, names, slugs, hierarchy levels, and parent relationships) which is essential when creating products or mapping categories across different sales channels. The endpoint supports flexible querying by slug, hierarchy level, department ID, or specific L3 category IDs, along with pagination for handling extensive category trees.

Request Type: GET
Scheme: HTTPS
Endpoint: https://{{host}}/v3/catalog/category

Try out Fynd Konnect's Fetch Categories Endpoint


Common Request Headers

HeaderMandatoryDescription
x-access-tokenYesAccess token used for authenticating API requests to Fynd Konnect
Content-TypeYesapplication/json
Want to create a custom L3 category?
  1. Prepare details: target L1/L2 parent, proposed L3 name & slug, business rationale (channels it serves), sample SKUs, and any required attributes
  2. Share this with your Fynd Onboarding POC (and raise a support ticket) for review
  3. Once created by Fynd, fetch the new category via API and update your mappings

Query Parameters

slugstring

Retrieve a category by its unique slug identifier

levelinteger

Filter categories by hierarchy level (1 for L1, 2 for L2, 3 for L3)

Enum123
departmentinteger

Filter categories by department ID (UID) from Fetch Departments

cat3_idArray of integers

Comma-separated list of L3 category IDs (UIDs) to fetch multiple leaf categories in a single request

page_numberinteger>= 1

Page number for pagination (default: 1)

page_sizeinteger[ 1 .. 200 ]

Number of items to retrieve per page (default: 10)

Filtering Tips
  • Use slug for exact category lookups by slug identifier
  • Use level to retrieve all categories at a specific hierarchy level
  • Combine department and level to get categories within a department at a specific level
  • Use cat3_id with comma-separated IDs to fetch multiple L3 categories efficiently
  • Apply pagination when dealing with large category trees (e.g., fashion or grocery catalogs)

Success Response

itemsArray of objects

List of categories matching the query filters

page_numberinteger

Current page number

page_sizeinteger

Page size used for this response

totalinteger

Total number of records available matching the query

API Call Example

curl -i -X GET \
  'https://fyndkonnect.konnect.uat.fyndx1.de/v3/catalog/category?slug=string&level=1&department=0&cat3_id=0&page_number=1&page_size=1' \
  -H 'x-access-token: YOUR_API_KEY_HERE'

Example Response

{
  "items": [
    {
      "id": 142037,
      "name": "Fruit Juices & Fruit Drinks",
      "slug": "fruit-juices-and-fruit-drinks",
      "level": 3,
      "parent_id": 8123,
      "department_id": 5957,
      "path": [
        {
          "id": 101,
          "name": "Beverages",
          "slug": "beverages",
          "level": 1
        },
        {
          "id": 8123,
          "name": "Juices",
          "slug": "juices",
          "level": 2
        },
        {
          "id": 142037,
          "name": "Fruit Juices & Fruit Drinks",
          "slug": "fruit-juices-and-fruit-drinks",
          "level": 3
        }
      ]
    }
  ],
  "page_number": 1,
  "page_size": 10,
  "total": 420
}

Best Practices

  1. Cache category data: Category hierarchies change infrequently, so implement caching to reduce API calls
  2. Use L3 categories for products: Always assign products to L3 (leaf) categories for maximum specificity
  3. Store category IDs: Save category IDs (UIDs) in your system for efficient product creation and updates
  4. Leverage the path array: Use the path field to build breadcrumbs and understand category relationships
  5. Filter by department: Combine department and level filters to retrieve relevant categories for specific product types
  6. Handle pagination: Fashion and grocery catalogs can have hundreds of categories; implement proper pagination logic
Next Steps
© 2026 Shopsense Retail Technologies | MadeInIndia