Categorylist Models

This directory contains the core data models and API endpoints for managing categorylists. A categorylist is a structured collection of product data organized into versions, revisions, and items.

Overview

The categorylist system is organized hierarchically:

Organization
└── Versions (major iterations)
    └── Revisions (working copies)
        ├── Labels (column definitions)
        ├── Items (product data)
        └── Features (additional item metadata)

Module Structure

Version

Manages categorylist versions - top-level containers that organize your categorylist data over time. Each version can contain multiple revisions.

Key Operations:

• List and create versions
• Get version details with all revisions

Revision

Manages revisions within versions - working copies where you make changes before publishing. Revisions contain labels, items, and features.

Key Operations:

• Create, update, and publish revisions
• Upload bulk data via CSV
• Get complete revision data

Labels

Manages label definitions - the underlying structure that defines columns in your categorylist. Labels specify column types, metadata, and display preferences.

Key Operations:

• Get and update label structures
• Manage column order (organization and user preferences)
• Get available label options based on PROs

Columns

Provides simplified column management operations built on top of labels. Easier interface for common column operations like add, rename, delete, and reorder.

Key Operations:

• Add, rename, and delete columns
• Manage column display order

Items

Manages product items within revisions. Items are the core data entities containing product information stored as key-value pairs.

Key Operations:

• List items with advanced filtering, searching, and pagination
• Create, update, and delete items
• Get filter options for building UIs

Features

Manages item features - additional metadata and properties attached to items. Useful for country-specific, report-specific, or PRO-specific information.

Key Operations:

• Create, update, and delete features
• Bulk feature operations
• Merge item and feature data
• Search and statistics

Common Workflows

Creating a New Categorylist

1. Create a Version (POST /versions)

   • Creates a new version with an initial draft revision

2. Define Labels (PUT /revisions/{revision_uuid}/labels)

   • Set up the column structure for your categorylist

3. Add Items (POST /items or bulk upload)

   • Add product data to the revision

4. Publish Revision (POST /revisions/{revision_uuid}/publish)

   • Finalize the revision when ready

Updating an Existing Categorylist

1. Get Current Revision (GET /revisions/{revision_uuid})

   • View the current published revision

2. Create New Draft (POST /revisions)

   • Create a new draft revision based on the published one

3. Make Changes

   • Update labels, add/remove columns, modify items

4. Publish New Revision (POST /revisions/{revision_uuid}/publish)

   • Publish the updated revision

Working with Items

1. List Items (GET /revisions/{revision_uuid}/items)

   • Retrieve items with filtering and pagination

2. Get Filter Options (GET /revisions/{revision_uuid}/filter-options)

   • Get available values for building filter UIs

3. Update Items (PUT /revisions/{revision_uuid}/items/{item_uuid})

   • Modify item data

Data Flow

Labels (Column Definitions)
    ↓
Items (Product Data using Labels)
    ↓
Features (Additional Item Metadata)

• Labels define what columns are available
• Items store data using label column names as keys
• Features add additional context-specific data to items

Permissions

Most operations require the CATEGORYLIST_SUGGEST-EDIT permission. Some administrative operations (like creating versions) require CATEGORYLIST_ADMIN permission.

API Base Path

All endpoints are prefixed with /saas/categorylist/.

Related Documentation

• Categorylist Overview - High-level categorylist documentation
• Individual module READMEs linked above for detailed information