API Batch Import

API batch import allows you to programmatically upload your entire product catalog to Youzu.ai using our API. This method is ideal for large catalogs and automated systems.

Benefits of API Batch Import

Automation - Easily integrate with your existing systems
Bulk processing - Upload thousands of products in a single operation
Scheduled updates - Implement regular synchronization on your schedule
Format flexibility - Support for both JSON and CSV data formats

Authentication

All API endpoints require authentication using your secret key. Include your secret key in the request header:

Authorization: Bearer YOUR_SECRET_KEY

Import Methods

Youzu.ai supports two primary formats for batch imports:

JSON Import - Structured product data in JSON format
CSV Import - Tabular product data in CSV format

JSON Import

Endpoint

POST https://platform-api.youzu.ai/api/v1/products/import

Request Format

{
  "products": [
    {
      "product_id": "prod_12345",
      "name": "Ergonomic Office Chair",
      "description": "Premium office chair with lumbar support",
      "price": 299.99,
      "currency": "USD",
      "images": [
        {
          "url": "<https://example.com/images/chair_front.jpg>",
          "position": 1,
          "alt": "Front view of office chair"
        }
      ],
      "categories": ["Furniture", "Office"],
      "tags": ["ergonomic", "office", "comfortable"],
      "variants": [
        {
          "id": "var_789",
          "attributes": {
            "color": "Black",
            "material": "Leather"
          }
        }
      ],
      "metadata": {
        "inventory_count": 42,
        "featured": true
      }
    },
    // Additional products...
  ]
}

Required Fields

Field	Type	Description
`product_id`	String	Unique identifier for the product
`name`	String	Product name
`description`	String	Product description
`price`	Number	Product price
`currency`	String	Three-letter currency code (e.g., USD)
`images`	Array	At least one product image

Example: JavaScript

const youzu = new YouzuAPI({
  secretKey: 'YOUR_SECRET_KEY'
});

const productData = {
  products: [
    {
      product_id: "prod_12345",
      name: "Ergonomic Office Chair",
      description: "Premium office chair with lumbar support",
      price: 299.99,
      currency: "USD",
      images: [
        {
          url: "<https://example.com/images/chair_front.jpg>",
          position: 1
        }
      ],
      categories: ["Furniture", "Office"]
    },
    // Additional products...
  ]
};

try {
  const result = await youzu.products.batchImport(productData);
  console.log(`Imported ${result.importedCount} products`);
  console.log(`Import ID: ${result.importId}`);
} catch (error) {
  console.error('Error importing products:', error);
}

Example: Python

import youzu

youzu.secret_key = "YOUR_SECRET_KEY"

product_data = {
    "products": [
        {
            "product_id": "prod_12345",
            "name": "Ergonomic Office Chair",
            "description": "Premium office chair with lumbar support",
            "price": 299.99,
            "currency": "USD",
            "images": [
                {
                    "url": "<https://example.com/images/chair_front.jpg>",
                    "position": 1
                }
            ],
            "categories": ["Furniture", "Office"]
        },
        // Additional products...
    ]
}

try:
    result = youzu.products.batch_import(product_data)
    print(f"Imported {result['imported_count']} products")
    print(f"Import ID: {result['import_id']}")
except Exception as e:
    print(f"Error importing products: {e}")

CSV Import

Endpoint

POST https://platform-api.youzu.ai/api/v1/products/import/csv

CSV Format Requirements

You must include these required columns:

product_id (unique identifier)
name (product name)
description (product description)
price (product price as decimal)
currency (three-letter currency code)
image_url (primary product image URL)

Optional columns include:

categories (comma-separated list)
tags (comma-separated list)
variant_id (for product variants)
variant_attributes (JSON string of attributes)

Example CSV

product_id,name,description,price,currency,image_url,categories,tags
prod_12345,Ergonomic Office Chair,Premium office chair with lumbar support,299.99,USD,<https://example.com/images/chair_front.jpg>,"Furniture,Office","ergonomic,office,comfortable"
prod_67890,Standing Desk,Adjustable height standing desk,499.99,USD,<https://example.com/images/desk.jpg>,"Furniture,Office","ergonomic,standing,adjustable"

Example: JavaScript

const fs = require('fs');
const youzu = new YouzuAPI({
  secretKey: 'YOUR_SECRET_KEY'
});

const csvFile = fs.readFileSync('/path/to/products.csv');
const form = new FormData();
form.append('file', csvFile, 'products.csv');

try {
  const result = await youzu.products.importCsv(form);
  console.log(`Import job created: ${result.importId}`);
} catch (error) {
  console.error('Error importing CSV:', error);
}

Example: Python

import youzu

youzu.secret_key = "YOUR_SECRET_KEY"

with open('/path/to/products.csv', 'rb') as file:
    try:
        result = youzu.products.import_csv(file)
        print(f"Import job created: {result['import_id']}")
    except Exception as e:
        print(f"Error importing CSV: {e}")

Checking Import Status

To monitor the progress of a batch import operation:

Endpoint

GET https://platform-api.youzu.ai/api/v1/products/import/{importId}/status

Example: JavaScript

const importId = 'imp_87654321';

try {
  const status = await youzu.products.getImportStatus(importId);
  console.log(`Status: ${status.state}`);
  console.log(`Progress: ${status.progress}%`);
  console.log(`Processed: ${status.processedCount} / ${status.totalCount} products`);
  console.log(`Errors: ${status.errorCount}`);
} catch (error) {
  console.error('Error checking import status:', error);
}

Example: Python

import youzu

youzu.secret_key = "YOUR_SECRET_KEY"

import_id = "imp_87654321"

try:
    status = youzu.products.get_import_status(import_id)
    print(f"Status: {status['state']}")
    print(f"Progress: {status['progress']}%")
    print(f"Processed: {status['processed_count']} / {status['total_count']} products")
    print(f"Errors: {status['error_count']}")
except Exception as e:
    print(f"Error checking import status: {e}")

Property Mapping

Youzu.ai expects product data with specific attribute names, but we understand that your existing systems may use different naming conventions. Our property mapping feature allows you to map your property names to our expected format without changing your source data.

Using Property Mapping in API Requests

You can include a property map in your import requests to specify how your fields should be mapped to Youzu.ai's expected fields.

JSON Import with Property Map

{
  "products": [ ... ],
  "propertyMap": {
    "item_id": "product_id",
    "title": "name",
    "long_description": "description",
    "retail_price": "price",
    "currency_code": "currency",
    "product_images": "images",
    "product_type": "categories",
    "product_attributes": "metadata"
  }
}

CSV Import with Property Map

For CSV imports, include the property map in the request parameters:

const youzu = new YouzuAPI({
  secretKey: 'YOUR_SECRET_KEY'
});

const form = new FormData();
form.append('file', csvFile, 'products.csv');

const propertyMap = {
  "item_id": "product_id",
  "title": "name",
  "long_description": "description",
  "retail_price": "price",
  "currency_code": "currency",
  "main_image": "image_url",
  "product_type": "categories",
  "product_attributes": "metadata"
};

form.append('propertyMap', JSON.stringify(propertyMap));

try {
  const result = await youzu.products.importCsv(form);
  console.log(`Import job created: ${result.importId}`);
} catch (error) {
  console.error('Error importing CSV:', error);
}

Nested Property Mapping

For complex data structures, you can specify paths to nested properties using dot notation:

{
  "propertyMap": {
    "item.id": "product_id",
    "item.basic_info.title": "name",
    "item.basic_info.description": "description",
    "pricing.base_amount": "price",
    "pricing.currency": "currency",
    "media.main_image.url": "images[0].url"
  }
}

Supported Mapping Types

Source Data Type	Target Data Type	Description
String	String	Direct mapping
Number	Number	Direct mapping
Array	Array	Maps array elements
Object	Object	Maps nested properties
String (comma-separated)	Array	Converts comma-separated string to array
Object Array	Object Array	Maps properties of each object in array

Saving and Reusing Property Maps

You can save and retrieve property maps for reuse:

// Save a property map
const result = await youzu.propertyMaps.create({
  name: "Shopify Export Format",
  map: propertyMap
});

// Use a saved property map in an import
const importResult = await youzu.products.batchImport({
  products: productData,
  propertyMapId: "map_12345"
});

Handling Import Errors

If errors occur during import, you can retrieve detailed error information:

Endpoint

GET https://platform-api.youzu.ai/api/v1/products/import/{importId}/errors

Example: JavaScript

const importId = 'imp_87654321';

try {
  const errors = await youzu.products.getImportErrors(importId);
  errors.items.forEach(error => {
    console.log(`Row ${error.rowNumber}: ${error.message}`);
    console.log(`Product ID: ${error.productId}`);
    console.log(`Data: ${JSON.stringify(error.data)}`);
    console.log('---');
  });
} catch (error) {
  console.error('Error retrieving import errors:', error);
}

Best Practices

Split large catalogs - For very large catalogs, split imports into batches of 10,000 products or fewer
Include complete data - Provide as much product information as possible for optimal AI performance
Use high-quality images - Include multiple high-resolution images for each product
Schedule regular updates - Keep your product catalog in sync with regular imports

For further assistance with API batch imports, contact our support team at support@youzu.ai.