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

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
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

Generated Fields
- id: Unique product identifier
- price: Calculated from variants
- stock: Sum of variant stocks
- createdAt: Creation timestamp
- updatedAt: Last modification time
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

Product Fields
- name: Required, max 255 characters
- category: Required, must be valid category
- descriptionHtml: Required, valid HTML
- images: At least one image required
Options
- Option names must be unique
- At least one value per option
- Values must be strings
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"
    }
  ]
}

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

💡 Best Practices

Product Setup
- Use clear, descriptive names
- Provide detailed HTML descriptions
- Include multiple product images
- Set appropriate categories and tags
Variant Management
- Use meaningful SKUs
- Maintain accurate stock levels
- Set competitive pricing
- Include variant-specific images
Performance
- Optimize image sizes
- Use WebP format
- Batch variant creation
- Cache frequent requests

🔹 Endpoint Details​

🔒 Authentication​

📝 Request Structure​

Required Fields​

Optional Fields​

📘 Field Interpretation​

🎯 Request Examples​

Basic Product (No Options)​

Product with Options​

Integration Product​

📤 Response Example​

📘 Response Interpretation​

📘 Notes​

✅ Common Use Cases​

🔍 Validation Rules​

❌ Error Responses​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

409 Conflict​

422 Validation Error​

🔗 Related Endpoints​

💡 Best Practices​

🔹 Endpoint Details

🔒 Authentication

📝 Request Structure

Required Fields

Optional Fields

📘 Field Interpretation

🎯 Request Examples

Basic Product (No Options)

Product with Options

Integration Product

📤 Response Example

📘 Response Interpretation

📘 Notes

✅ Common Use Cases

🔍 Validation Rules

❌ Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

409 Conflict

422 Validation Error

🔗 Related Endpoints

💡 Best Practices