Create Product

This endpoint creates a new product with its variants in the system. The product can have multiple variants, each representing a specific combination of options.

🔹 Endpoint Details

POST /api/v1/products

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure

Required Fields

Field	Type	Description	Example
name	string	Product name	"Premium T-Shirt"
category	string	Product category	"Apparel"
description	string	Product description	"High-quality t-shirt"
descriptionHtml	string	HTML description	"<p>High-quality t-shirt</p>"
images	string[]	Product images	["https://example.com/shirt.webp"]
variants	Variant[]	Product variants	See below

Optional Fields

Field	Type	Description	Default
active	boolean	Product status	true
options	Option[]	Available options	[]
externalId	string	External identifier	-
providerType	string	Provider type	"onlive"
tags	string[]	Product tags	[]

📘 Field Interpretation

1. Required Fields

   • name: Choose a unique, descriptive name
   • category: Must match existing system categories
   • descriptionHtml: Can include full HTML markup
   • images: Main product images, not variant-specific
   • variants: At least one variant required

2. Optional Fields

   • active: Controls visibility in catalogs
   • options: Define variant characteristics
   • externalId: For external system integration
   • providerType: Integration platform type
   • tags: For filtering and categorization

🎯 Request Examples

Basic Product (No Options)

{
    "name": "Basic T-Shirt",
    "category": "Apparel",
    "description": "Classic cotton t-shirt",
    "descriptionHtml": "<p>Classic cotton t-shirt</p>",
    "images": ["https://example.com/shirt.webp"],
    "variants": [
        {
            "sku": "BTS-001",
            "price": 19.99,
            "currency": "EUR",
            "stock": 100,
            "selectedOptions": [],
            "images": ["https://example.com/shirt.webp"]
        }
    ]
}

Product with Options

{
    "name": "Premium T-Shirt",
    "category": "Apparel",
    "description": "High-quality cotton t-shirt",
    "descriptionHtml": "<p>High-quality cotton t-shirt</p>",
    "images": [
        "https://example.com/shirt-front.webp",
        "https://example.com/shirt-back.webp"
    ],
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large"]
        },
        {
            "name": "Color",
            "values": ["Black", "White"]
        }
    ],
    "variants": [
        {
            "sku": "TS-BLK-S",
            "price": 29.99,
            "currency": "EUR",
            "stock": 50,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "Black"
                }
            ],
            "images": [
                "https://example.com/shirt-black-small.webp"
            ]
        },
        {
            "sku": "TS-WHT-M",
            "price": 29.99,
            "currency": "EUR",
            "stock": 30,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Medium"
                },
                {
                    "name": "Color",
                    "value": "White"
                }
            ],
            "images": [
                "https://example.com/shirt-white-medium.webp"
            ]
        }
    ],
    "tags": ["apparel", "t-shirt", "premium"],
    "providerType": "onlive"
}

Integration Product

{
    "name": "Shopify Premium Shirt",
    "category": "Apparel",
    "description": "Imported from Shopify",
    "descriptionHtml": "<p>Imported from Shopify</p>",
    "images": ["https://shopify-cdn.com/shirt.webp"],
    "externalId": "shopify_12345",
    "providerType": "shopify-public",
    "variants": [
        {
            "sku": "SHOP-TS-001",
            "price": 39.99,
            "currency": "EUR",
            "stock": 50,
            "externalId": "shopify_variant_123",
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Large"
                }
            ],
            "images": ["https://shopify-cdn.com/shirt-l.webp"]
        }
    ]
}

📤 Response Example

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Premium T-Shirt",
    "category": "Apparel",
    "description": "High-quality cotton t-shirt",
    "descriptionHtml": "<p>High-quality cotton t-shirt</p>",
    "images": [
        "https://example.com/shirt-front.webp",
        "https://example.com/shirt-back.webp"
    ],
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large"]
        },
        {
            "name": "Color",
            "values": ["Black", "White"]
        }
    ],
    "variants": [
        {
            "id": "789f0123-c45b-67d8-e901-234567890000",
            "sku": "TS-BLK-S",
            "price": 29.99,
            "currency": "EUR",
            "stock": 50,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "Black"
                }
            ],
            "images": [
                "https://example.com/shirt-black-small.webp"
            ]
        },
        // Additional variants...
    ],
    "price": 29.99,
    "stock": 80,
    "tags": ["apparel", "t-shirt", "premium"],
    "providerType": "onlive",
    "active": true,
    "createdAt": "2025-05-22T10:00:00Z",
    "updatedAt": "2025-05-22T10:00:00Z"
}

📘 Response Interpretation

1. Generated Fields

   • id: Unique product identifier
   • price: Calculated from variants
   • stock: Sum of variant stocks
   • createdAt: Creation timestamp
   • updatedAt: Last modification time

2. Variant Fields

   • Each variant gets a unique id
   • Stock and price are per variant
   • Images can be variant-specific

📘 Notes

• The organizationId is automatically set from your authentication credentials
• At least one variant is required for each product
• Each variant must have a unique combination of options
• The product's price is derived from variants
• The product's stock is the sum of variant stocks
• All images must be in WebP format
• All currency codes must follow ISO 4217 format

✅ Common Use Cases

• 🏪 New Product: Create a product with basic variants
• 🎨 Custom Product: Set up products with multiple options
• 📦 Initial Stock: Set up initial inventory levels
• 🔄 Platform Import: Import products from other systems
• 🏷️ Categorized Items: Create products in specific categories

🔍 Validation Rules

1. Product Fields

   • name: Required, max 255 characters
   • category: Required, must be valid category
   • descriptionHtml: Required, valid HTML
   • images: At least one image required

2. Options

   • Option names must be unique
   • At least one value per option
   • Values must be strings

3. Variants

   • At least one variant required
   • Unique SKUs across variants
   • Valid option combinations
   • Positive prices
   • Non-negative stock values

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "category",
      "message": "Category does not exist"
    },
    {
      "field": "descriptionHtml",
      "message": "Invalid HTML markup"
    }
  ]
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to create products"
}

409 Conflict

{
  "statusCode": 409,
  "message": "A variant with this SKU already exists"
}

422 Validation Error

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "variants",
      "message": "At least one variant is required"
    }
  ]
}

🔗 Related Endpoints

• Update Product: Modify existing products
• Get Product: Retrieve product details
• Delete Product: Remove products
• Product Properties: Field definitions

💡 Best Practices

1. Product Setup

   • Use clear, descriptive names
   • Provide detailed HTML descriptions
   • Include multiple product images
   • Set appropriate categories and tags

2. Variant Management

   • Use meaningful SKUs
   • Maintain accurate stock levels
   • Set competitive pricing
   • Include variant-specific images

3. Performance

   • Optimize image sizes
   • Use WebP format
   • Batch variant creation
   • Cache frequent requests