Product Catalog API - Overview and Terminology

Overview

The Product Catalog API allows you to manage product configurations, attributes, and customer-specific product offerings. This API provides the foundation for creating customizable products that customers can order through the Order Intake system.

The API follows RESTful principles and supports the complete lifecycle of product management - from defining basic product structures to creating customer-specific product configurations with variant options that generate unique ProductUIDs for ordering.

Core Concepts and Terminology

Product Model

A Product Model defines the structure and capabilities of a product type. It represents the "blueprint" of what can be produced.

Examples: - T-shirt product model - Poster product model
- Business card product model - Framed poster product model

Key characteristics: - Defines the physical structure (single part or multi-part) - Specifies available attributes (color, size, material, etc.) - Contains metadata like preview images and descriptions - Serves as the basis for creating customer products

Parts and Multi-Part Products

Parts are individual components that make up a product model. Products can be:

• Single Part: Simple products with one component (e.g., a basic poster)
• Multi-Part: Complex products with multiple components (e.g., framed poster that consists of frame + poster parts)

Examples of multi-part products: - Framed Poster: frame part + poster part - Book: cover part + inner pages part

Attributes

Attributes define the customizable characteristics of a product. They represent the different ways a product can be varied or customized.

Common attribute types: - Color: Defines color options (red, blue, green, etc.) - Size: Defines size options (small, medium, large, etc.) - Material: Defines material options (cotton, polyester, silk, etc.) - Format: Defines format options (A4, A3, custom dimensions, etc.) - Finish: Defines finishing options (matte, glossy, laminated, etc.)

Key characteristics: - Attributes are reusable across multiple product models - Each attribute can have multiple values - Attributes define what aspects of a product can be customized

Attribute Values

Attribute Values are the specific options available for each attribute. They represent the actual choices customers can make.

Examples: - Color attribute values: red, blue, green, black, white - Size attribute values: small, medium, large, xl, xxl - Material attribute values: cotton, polyester, silk, wool

Key characteristics: - Each value has a unique identifier (used in ProductUIDs) - Values can have additional properties (hex codes for colors, dimensions for sizes) - Values can be marked as default options - Values can be custom (accepting any input) or predefined

ProductUID

A ProductUID is a unique identifier that represents a specific product configuration with all its attribute values. It's automatically generated based on the product model and selected attribute values.

Format: {product-model-template} with attribute values filled in

Example: poster_paper_premium_size_100x100-mm

Key characteristics: - Automatically generated when variant option values are created - Used by the Order Intake system to place orders - Represents a specific, orderable product configuration - Unique across the entire system

Customer Product

A Customer Product is a specific product configuration that customers can order. It combines a product model with defined variant options and specifies which customers can access it.

Key characteristics: - Based on a single product model - Defines available variant options (size, color, etc.) - Specifies which customers can order it - Contains business logic for product configuration

Example:

{
  "name": "Premium T-Shirt",
  "productModelId": "model-tshirt-001",
  "customerIds": ["customer-123", "customer-456"],
  "variantOptions": [
    {"id": "size", "name": "Size"},
    {"id": "color", "name": "Color"}
  ]
}

Variant Options

Variant Options define the ways customers can customize a customer product. They group related attributes together and define which attributes apply to which parts of the product.

Examples: - Size variant option: Maps to width/height attributes for both frame and poster parts - Color variant option: Maps to color attributes for fabric parts - Material variant option: Maps to material type attributes for specific parts

Key characteristics: - Each variant option has a unique identifier - Maps to specific attributes on specific product parts - Defines the customization interface for customers

Variant Option Values

Variant Option Values are the actual selectable options within each variant option. They define the specific combinations of attribute values that customers can choose.

Example for a "size" variant option:

{
  "variantOptionId": "size",
  "values": [
    {
      "value": "8x10",
      "attributeValues": [
        {
          "partModelId": "frame",
          "attributes": {"width": "8", "height": "10"}
        },
        {
          "partModelId": "poster",
          "attributes": {"width": "8", "height": "10"}
        }
      ]
    }
  ]
}