Product Data Requirements

For optimal performance of Youzu.ai's visual AI features, it's important to ensure your product data meets our recommended specifications. This guide outlines the requirements and best practices for structuring your product data.

Required Fields

All product records must include these essential fields:

Field	Type	Description	Example
`name`	TranslatedField	Product name in multiple languages	`{"en": "Ergonomic Office Chair"}`
`description`	TranslatedField	Product description in multiple languages	`{"en": "Premium office chair with lumbar support"}`
`sku`	String	Stock keeping unit	`"CHAIR-001"`
`external_ref`	String	External reference in format COMPANY:PLATFORM:VERSION:RESOURCE	`"ACME:ECOMMERCE:V1:PRODUCT:12345"`
`url`	String (URL)	Product URL	`"https://shop.example.com/products/chair"`
`price`	PriceField	Price in multiple currencies	`{"USD": 299.99, "EUR": 259.99}`
`in_stock`	Boolean	Whether the product is in stock	`true`
`is_published`	Boolean	Whether the product is published	`true`
`images`	Array	List of image URLs (required for visual AI)	`["https://example.com/image1.jpg"]`

TranslatedField Format

For fields that support multiple languages (like name and description), use the TranslatedField format:

{
  "name": {
    "en": "Blue Sofa",
    "es": "Sofá Azul",
    "fr": "Canapé Bleu"
  },
  "description": {
    "en": "Comfortable 3-seater sofa with fabric upholstery",
    "es": "Sofá de 3 plazas cómodo con tapizado de tela"
  }
}

PriceField Format

For the price and price_discount fields, specify prices in multiple currencies:

{
  "price": {
    "USD": 299.99,
    "EUR": 259.99,
    "GBP": 219.99
  },
  "price_discount": {
    "USD": 249.99,
    "EUR": 219.99
  }
}

External Reference Format

The external_ref field must follow the format: COMPANY:PLATFORM:VERSION:RESOURCE:ID

{
  "external_ref": "ACME:ECOMMERCE:V1:PRODUCT:12345"
}

Optional Fields

These fields provide additional product information:

Field	Type	Description	Example
`ean`	String	European Article Number	`"1234567890123"`
`upc`	String	Universal Product Code	`"123456789012"`
`dimensions`	Object	Product dimensions in cm	`{"width": 60, "height": 120, "length": 70}`
`weight_kg`	Number	Weight in kilograms	`15.5`
`colour`	Object	Color information	See Colour Format
`brand`	String	Brand name	`"ErgoDesigns"`
`categories`	Array	List of category names	`["Furniture", "Office"]`
`vendors`	Array	List of vendor names	`["Vendor A", "Vendor B"]`
`custom_properties`	Object	Custom properties for filtering and querying (max 10 items). You can use any key name with any primitive value (string, number, boolean).	`{"material": "Leather", "has_warranty": true}`

Dimensions Format

Physical dimensions should be specified in centimeters:

{
  "dimensions": {
    "width": 60,
    "height": 120,
    "length": 70
  }
}

Colour Format

Color information with primary and secondary colors:

{
  "colour": {
    "primary": "Blue",
    "secondary": "Navy"
  }
}

Images Format

Images should be provided as an array of URLs:

{
  "images": [
    "https://example.com/images/chair_front.jpg",
    "https://example.com/images/chair_side.jpg",
    "https://example.com/images/chair_detail.jpg"
  ]
}

Custom Properties

Custom properties allow you to add up to 10 additional key-value pairs that you can later use to filter and query products. You have complete flexibility to define any key names and use any primitive values (string, number, or boolean).

{
  "custom_properties": {
    "material": "Leather",
    "warranty": "2 years",
    "assembly_required": true,
    "shipping_weight_kg": 12.5
  }
}

These properties can be used to create custom filters and search criteria when querying your product catalog.

Complete Example

{
  "name": {
    "en": "Ergonomic Office Chair",
    "es": "Silla de Oficina Ergonómica"
  },
  "description": {
    "en": "Premium office chair with lumbar support and adjustable height",
    "es": "Silla de oficina premium con soporte lumbar y altura ajustable"
  },
  "sku": "CHAIR-001",
  "external_ref": "ACME:ECOMMERCE:V1:PRODUCT:12345",
  "ean": "1234567890123",
  "upc": "123456789012",
  "url": "https://shop.example.com/products/chair",
  "price": {
    "USD": 299.99,
    "EUR": 259.99
  },
  "price_discount": {
    "USD": 249.99
  },
  "in_stock": true,
  "is_published": true,
  "dimensions": {
    "width": 60,
    "height": 120,
    "length": 70
  },
  "weight_kg": 15.5,
  "colour": {
    "primary": "Black",
    "secondary": "Grey"
  },
  "brand": "ErgoDesigns",
  "categories": ["Furniture", "Office", "Chairs"],
  "vendors": ["Vendor A"],
  "images": [
    "https://example.com/images/chair_front.jpg",
    "https://example.com/images/chair_side.jpg",
    "https://example.com/images/chair_detail.jpg"
  ],
  "custom_properties": {
    "material": "Leather",
    "warranty": "2 years",
    "assembly_required": "Yes"
  }
}

Image Requirements

Images are crucial for Youzu.ai's visual AI functionality. For best results:

Technical Specifications

Resolution: Minimum 800x800 pixels, recommended 1200x1200 pixels or higher
Format: JPEG, PNG, or WebP
File size: Maximum 10MB per image
Background: White or transparent backgrounds preferred
Quantity: At least one image per product, multiple images recommended

Image Quality Best Practices

Use well-lit, professional product photography
Show the product from multiple angles (front, side, back, detail shots)
Avoid text overlays or watermarks on the image
Ensure the product fills at least 80% of the image frame
Maintain consistent lighting and background across product images

Overview

Real-time Import