Product Properties

This table defines the structure of the product entity, including all properties and their descriptions. Products in the system can have multiple variants, each representing a specific combination of options (e.g., size and color).

🔑 Core Properties

Property	Type	Required	Example	Description
name	string	Yes	"Premium T-Shirt"	Name of the product
active	boolean	No	true	Indicates if the product is active
category	string	Yes	"Apparel"	Category to which the product belongs
descriptionHtml	string	Yes	"<p>High-quality cotton t-shirt</p>"	HTML description of the product
handle	string	No	"premium-t-shirt"	URL-friendly identifier

📘 Interpretation

• name should be unique and descriptive
• active controls visibility in listings (defaults to true)
• category helps organize products in the catalog
• descriptionHtml supports full HTML markup for rich descriptions
• handle is auto-generated if not provided

🎯 Example Use Cases

{
    "name": "Premium T-Shirt",
    "active": true,
    "category": "Apparel",
    "descriptionHtml": "<p>High-quality cotton t-shirt featuring:</p><ul><li>100% organic cotton</li><li>Premium stitching</li></ul>",
    "handle": "premium-t-shirt"
}

🏷️ Identification

Property	Type	Required	Example	Description
externalId	string	No	"SHIRT-001"	External identifier
token	string	No	"prod_123abc"	Token for identification
sku	string	No	"SKU123"	Stock Keeping Unit
gtin	string	No	"123456789"	Global Trade Item Number

📘 Interpretation

• externalId links to external systems
• token is system-generated for internal reference
• sku is used for inventory management
• gtin supports standard product identification

💰 Pricing & Stock

Property	Type	Required	Example	Description
price	number	No	29.99	Base price (derived from variants)
currency	string	No	"EUR"	Currency code (ISO 4217)
stock	number	No	100	Total stock (summed from variants)

📘 Interpretation

• price is automatically calculated from variants
• currency must use standard ISO 4217 codes
• stock is automatically summed from variant stocks

⚠️ Important Notes

• Prices should have max 2 decimal places
• Currency must be consistent across variants
• Stock cannot be negative

🖼️ Media

Property	Type	Required	Example	Description
images	string[]	Yes	["https://example.com/shirt.webp"]	Product images (WebP)
vodUrl	string	No	"https://vod.example.com/123"	Video on demand URL
url	string	No	"https://store.example.com/shirt"	Product URL

📘 Interpretation

• images must be WebP format for optimal performance
• vodUrl supports product video content
• url provides direct link to product page

🖼️ Image Guidelines

• Minimum resolution: 800x800px
• Maximum file size: 2MB
• Format: WebP only
• Aspect ratio: 1:1 (square)

🎨 Product Options

Options define the available choices for variants (e.g., size, color). Each option has a name and possible values:

{
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large"]
        },
        {
            "name": "Color",
            "values": ["Black", "White", "Red"]
        }
    ]
}

📘 Interpretation

• Option names must be unique per product
• Values must be strings
• At least one option value required
• Options create variant matrix

📦 Product Variants

Each variant represents a specific combination of options with its own pricing and inventory:

Property	Type	Required	Example	Description
externalId	string	No	"VAR-001"	External variant ID
sku	string	No	"SKU123-BLK-L"	Variant SKU
price	number	Yes	29.99	Variant price
currency	string	Yes	"EUR"	Currency code
stock	number	Yes	50	Available stock
images	string[]	Yes	["https://example.com/black-l.webp"]	Variant images
selectedOptions	OptionValue[]	Yes	See below	Selected option values

Selected Options Structure

{
    "variants": [
        {
            "sku": "TS-BLK-L",
            "price": 29.99,
            "currency": "EUR",
            "stock": 50,
            "images": ["https://example.com/black-l.webp"],
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Large"
                },
                {
                    "name": "Color",
                    "value": "Black"
                }
            ]
        }
    ]
}

📘 Interpretation

• Each variant must have unique option combinations
• SKUs must be unique across all variants
• Stock values must be non-negative
• Prices must be positive
• Images should show specific variant

📝 Validation Rules

1. Core Properties

   • Name: 2-255 characters
   • Category: Must exist in system
   • Description: Valid HTML, max 50000 characters

2. Options & Variants

   • At least one variant required
   • All option combinations must be unique
   • SKUs must be unique globally
   • Price > 0
   • Stock >= 0

3. Media

   • At least one image required
   • Images must be WebP format
   • URLs must be HTTPS
   • Valid video URL for vodUrl

📘 Notes

• Images must be in WebP format for optimal performance
• Currency codes must follow ISO 4217 format (e.g., 'EUR', 'USD')
• Price and stock are computed from variants
• Provider type must be one of: 'onlive', 'shopify-private', 'shopify-public', 'moddo', 'prestashop', 'woocommerce'
• HTML description should contain valid markup
• Each variant must have a unique combination of options

✅ Common Use Cases

• 🏪 Product Setup: Create basic product with variants
• 🎨 Custom Products: Configure multiple options and variants
• 📦 Inventory Management: Track stock across variants
• 💰 Price Management: Set different prices per variant
• 🔄 E-commerce Integration: Connect with external platforms
• 🏷️ Product Organization: Use categories and tags
• 🖼️ Media Management: Handle product and variant images