Catalog Management

The Brand catalog is the master source of truth for product data on the Blindstrader platform. Everything a Supplier sells, and everything a Retailer offers, ultimately traces back to your Brand catalog.

Catalog Structure

Brand Catalog
├── Fabrics          — Raw materials (colour, texture, opacity, dimensions)
├── Blind Types      — Product templates referencing fabrics
├── Option Sets      — Configurable options: controls, mounting, sizing ranges
└── Catalog Versions — Immutable snapshots published to Suppliers

Fabrics

Fabrics are the base components of any product. Each fabric record includes:

Field	Description
name	Marketing name (e.g. "Vogue Blackout Ivory")
code	SKU / article code
material	Material type (polyester, linen, etc.)
opacity	sheer, translucent, room_darkening, blackout
min_width / max_width	Available width range in mm
min_drop / max_drop	Available drop range in mm
brand_verified	Boolean — whether this fabric carries your brand verification

Creating a Fabric

1. Go to Catalog → Fabrics → New Fabric.
2. Fill in all required fields.
3. Toggle Brand Verified to apply your verification badge.
4. Click Save.

Blind Types

Blind types are product templates that combine one or more fabrics with a structural definition (roller blind, venetian, roman blind, etc.).

A blind type references:

• One or more compatible fabrics
• Valid option sets (controls, mounting types, sizing constraints)
• Assembly and fabrication instructions (for Supplier use)

Option Sets

Option sets define the configurable dimensions of a product. For example:

• Width steps: min 300mm, max 3000mm, step 1mm
• Drop steps: min 300mm, max 3000mm, step 1mm
• Control type: chain (left/right), motorised, spring
• Mounting: recess, face-fix, ceiling

Catalog Versioning

How Versions Work

Catalog versions are immutable, append-only records created automatically every time a catalog is published. You never create a version directly — it is a side-effect of the publish action.

Each publish atomically creates two records in a single database transaction:

Record	Table	Purpose
CatalogVersion	catalog_versions	The version entry with metadata (number, product count, changelog, timestamps)
CatalogVersionSnapshot	catalog_version_snapshots	A frozen JSON document of the full catalog state at publication time

If anything fails during publishing, both records are rolled back together — you will never have a version without a snapshot, or vice versa.

Version Numbering

Version numbers follow a monotonically increasing major-only scheme: 1.0, 2.0, 3.0, and so on. The number is assigned automatically — you cannot specify it. The .0 minor component is reserved for future patch-level releases.

Catalog Lifecycle (State Machine)

draft ──publish──▶ published ──archive──▶ archived
draft ──archive──▶ archived
draft | archived ──delete──▶ (soft-deleted)

Status	Meaning
draft	Work in progress, not visible to Suppliers
published	Available for Supplier import; cannot be deleted directly
archived	Permanently read-only; no updates, no new publishes, no new imports

WARNING

Published catalogs cannot be deleted without archiving first. This protects active Supplier permission grants from being silently invalidated.

Publishing is triggered via the API:

POST /api/v1/catalogs/{catalog}/publish

The platform then emits a BrandCatalogUpdated Kafka event. All connected Suppliers are notified and can choose whether to adopt the new version.

The Snapshot: Frozen Catalog State

The CatalogVersionSnapshot stores a complete JSON representation of the catalog at the exact moment of publication. It captures:

{
  "catalog": { /* catalog row as it existed at publish time */ },
  "version": { /* version row */ },
  "published": "2026-04-28T10:00:00+00:00"
}

Immutability is enforced at the model layer — any attempt to update a snapshot record after creation throws an exception.

This snapshot is what allows downstream services (Supplier, Retailer) to reconstruct any historical catalog state without querying the live Brand tenant database. A Supplier that adopted version 2.0 can always retrieve exactly what 2.0 looked like, even after version 5.0 has been published.

API Endpoints

Versions are read-only via the API. Version creation is a side-effect of publish — there is no POST /versions endpoint.

Method	Endpoint	Description
GET	/api/v1/catalogs/{catalog}/versions	List all versions, newest first
GET	/api/v1/catalogs/{catalog}/versions/{version}	Single version with embedded snapshot

The {catalog} and {version} path parameters accept the opaque public_id values (cat_… and catv_… prefixes respectively).

List response (GET /versions):

{
  "data": [
    {
      "id": "catv_abc123",
      "version_number": "2.0",
      "product_count": 42,
      "changelog": null,
      "published_at": "2026-04-28T10:00:00+00:00",
      "archived_at": null
    }
  ]
}

Detail response (GET /versions/{version}): same shape, plus the snapshot field:

{
  "data": {
    "id": "catv_abc123",
    "version_number": "2.0",
    "product_count": 42,
    "changelog": null,
    "published_at": "2026-04-28T10:00:00+00:00",
    "archived_at": null,
    "snapshot": {
      "id": "cvs_xyz789",
      "snapshot_data": {
        "catalog": { "...": "..." },
        "version": { "...": "..." },
        "published": "2026-04-28T10:00:00+00:00"
      }
    }
  }
}

Breaking vs Non-Breaking Changes

Non-breaking changes (safe to push)

Adding new fabrics, new option sets, or updating marketing copy.

Breaking changes (require Supplier opt-in)

Removing fabrics, changing SKU codes, altering dimensional constraints that would invalidate existing Supplier products.

Bulk Import

You can import fabrics and blind types in bulk via CSV under Catalog → Import → Upload CSV. Download the CSV template from the same page to ensure correct column formatting.

Product Lifecycle Management

When a fabric is discontinued:

1. Mark it as Discontinued in the fabric record.
2. It will no longer appear in new Supplier imports.
3. Existing Supplier products referencing the fabric are flagged with a discontinued_component warning.
4. Suppliers can then substitute with a newer fabric in their own catalog.