ForSURE.categorylist.models.items

Item models for the categorylist database.

Items Module

The Items module provides API endpoints for managing product items within categorylist revisions. Items represent individual products with their associated data (column values), SKUs, and status information.

Overview

Items are the core data entities in a categorylist. Each item belongs to a revision and contains:

  • A unique identifier (UUID)
  • A Stock Keeping Unit (SKU)
  • Data stored as key-value pairs where keys are column internal names (e.g., "general:SKU", "general:Product Name")
  • A status (PENDING, APPROVED, DELETED, etc.)
  • Metadata (creation/update timestamps, user information)

Main Use Cases

1. List Items

Retrieve items from a revision with advanced filtering, searching, and pagination:

  • Filter by country, report type, PRO, status, and more
  • Search across item data
  • Sort by any column
  • Paginate through large datasets
  • Select specific columns to return

Endpoint: GET /revisions/{revision_uuid}/items

2. Create Items

Add new items to a revision:

  • Create items with SKU and initial data
  • Create empty items (SKU auto-generated)

Endpoints:

  • POST /items - Create item with SKU and data
  • POST /revisions/{revision_uuid}/create - Create empty item

3. Update Items

Modify existing items:

  • Update entire item data
  • Update specific column values
  • Update items by SKU

Endpoints:

  • PUT /revisions/{revision_uuid}/items/{item_uuid} - Update full item
  • PUT /revisions/{revision_uuid}/items/{item_uuid}/column - Update single column
  • PUT /revisions/{revision_uuid}/items/sku/{sku} - Update by SKU

4. Delete Items

Remove items from a revision (soft delete):

  • Delete by item UUID
  • Delete by SKU

Endpoints:

  • DELETE /items/{item_uuid}
  • DELETE /revisions/{revision_uuid}/items/sku/{sku}
  • DELETE /revisions/{revision_uuid}/{item_uuid}

5. Get Filter Options

Retrieve available filter values for a specific column:

  • Get unique values for text/multi-select columns
  • Get min/max ranges for numeric columns
  • Useful for building filter UIs

Endpoint: GET /revisions/{revision_uuid}/filter-options?column={column_name}

Key Features

  • Pagination: All list endpoints support offset-based pagination
  • Advanced Filtering: Filter by multiple criteria simultaneously
  • Search: Full-text search across item data
  • Column Selection: Return only specific columns to reduce payload size
  • Status Management: Track item approval status and lifecycle
  • Soft Deletes: Items are marked as deleted, not permanently removed

Data Structure

Items store data as a dictionary where:

  • Keys: Column internal names (e.g., "general:SKU", "country:NL:WEEE:Weight")
  • Values: The actual data for that column (strings, numbers, etc.)

Permissions

All endpoints require the CATEGORYLIST_SUGGEST-EDIT permission.

  • Labels: Define the columns available for items
  • Features: Add additional metadata and properties to items
  • Revisions: Items belong to revisions within versions