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 field names use camelCase. The following fields are required on every product record. Fields marked (nullable) must be present but may be set to null.

Field	Type	Description	Example
`sku`	String	Stock keeping unit — unique within the catalogue	`"CHAIR-001"`
`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"}`
`url`	String (URL)	Product URL	`"https://shop.example.com/products/chair"`
`price`	PriceField	Price in multiple currencies	`{"USD": 299.99, "EUR": 259.99}`
`inStock`	Boolean	Whether the product is in stock	`true`
`isPublished`	Boolean	Whether the product is published	`true`
`images`	Array of URL strings	Product images (required for visual AI)	`["https://example.com/image1.jpg"]`
`dimensions`	Dimensions \| `null` (nullable)	Physical dimensions in centimetres	`{"widthCm": 60, "heightCm": 120, "lengthCm": 70}`
`weightKg`	Number \| `null` (nullable)	Weight in kilograms	`15.5`
`brand`	String \| `null` (nullable)	Brand name	`"ErgoDesigns"`

externalRef is not accepted from the client — the server generates it server-side from clientId, catalogueId, and sku in the format CLIENT:CATALOGUE:CATALOGUE_ID:PRODUCT:SKU.

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 priceDiscount fields, specify prices in multiple currencies:

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

Optional Fields

These fields provide additional product information:

Field	Type	Description	Example
`priceDiscount`	PriceField \| `null`	Discounted price in multiple currencies	`{"USD": 249.99}`
`ean`	String \| `null`	European Article Number	`"1234567890123"`
`upc`	String \| `null`	Universal Product Code	`"123456789012"`
`colour`	Object \| `null`	Colour information	See Colour Format
`categories`	Array of strings	Category names	`["Furniture", "Office"]`
`customProperties`	Object	Up to 10 custom key/value pairs for filtering (string, number, or boolean values)	`{"material": "Leather", "hasWarranty": true}`

Dimensions Format

Physical dimensions are in centimetres. All three axes are required when dimensions is not null.

{
  "dimensions": {
    "widthCm": 60,
    "heightCm": 120,
    "lengthCm": 70
  }
}

If you don't have dimensions for a product, pass null rather than omitting the key:

{
  "dimensions": null
}

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

customProperties lets you attach up to 10 additional key/value pairs for later filtering and search. Keys are free-form; values may be strings, numbers, or booleans.

{
  "customProperties": {
    "material": "Leather",
    "warranty": "2 years",
    "assemblyRequired": true,
    "shippingWeightKg": 12.5
  }
}

Complete Example

{
  "sku": "CHAIR-001",
  "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"
  },
  "url": "https://shop.example.com/products/chair",
  "price": {
    "USD": 299.99,
    "EUR": 259.99
  },
  "priceDiscount": {
    "USD": 249.99
  },
  "inStock": true,
  "isPublished": true,
  "images": [
    "https://example.com/images/chair_front.jpg",
    "https://example.com/images/chair_side.jpg",
    "https://example.com/images/chair_detail.jpg"
  ],
  "dimensions": {
    "widthCm": 60,
    "heightCm": 120,
    "lengthCm": 70
  },
  "weightKg": 15.5,
  "brand": "ErgoDesigns",
  "ean": "1234567890123",
  "upc": "123456789012",
  "colour": {
    "primary": "Black",
    "secondary": "Grey"
  },
  "categories": ["Furniture", "Office", "Chairs"],
  "customProperties": {
    "material": "Leather",
    "warranty": "2 years",
    "assemblyRequired": true
  }
}

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