Product Data Requirements

Each product submitted through JSON ingestion or a batch file uses the same customer-facing schema. Property names use camelCase. Validate the feed before submitting it so that ingestion can process records consistently.

Required Fields

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. Every key must be an uppercase three-letter ISO 4217 currency code, such as USD or EUR:

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

Colour information with primary and secondary colours:

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

Images Format

Images should be provided as an array of public HTTP or HTTPS URLs without embedded credentials. Youzu revalidates every redirect against public network addresses before downloading the image; private storage references such as s3:// are not accepted from customer feeds.

{
  "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 25 MiB per downloaded 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

Merchant API

Product Management