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

• 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

AuthenticationCopied!

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

Authorization: Bearer YOUR_SECRET_KEY
http Copy Copied!

Import MethodsCopied!

Youzu.ai supports two primary formats for batch imports:

1. JSON Import - Structured product data in JSON format
2. CSV Import - Tabular product data in CSV format

JSON ImportCopied!

EndpointCopied!

POST https://platform-api.youzu.ai/api/v1/products/import
http Copy Copied!

Request FormatCopied!

{
  "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...
  ]
}
json Copy Copied!

Required FieldsCopied!

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: JavaScriptCopied!

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);
}
javascript Copy Copied!

Example: PythonCopied!

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}")
python Copy Copied!

CSV ImportCopied!

EndpointCopied!

POST https://platform-api.youzu.ai/api/v1/products/import/csv
http Copy Copied!

CSV Format RequirementsCopied!

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

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"
csv Copy Copied!

Example: JavaScriptCopied!

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);
}
javascript Copy Copied!

Example: PythonCopied!

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}")
python Copy Copied!

Checking Import StatusCopied!

To monitor the progress of a batch import operation:

EndpointCopied!

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

Example: JavaScriptCopied!

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);
}
javascript Copy Copied!

Example: PythonCopied!

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}")
python Copy Copied!

Property MappingCopied!

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

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"
  }
}
json Copy Copied!

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);
}
javascript Copy Copied!

Nested Property MappingCopied!

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"
  }
}
json Copy Copied!

Supported Mapping TypesCopied!

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

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"
});
javascript Copy Copied!

Handling Import ErrorsCopied!

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

EndpointCopied!

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

Example: JavaScriptCopied!

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);
}
javascript Copy Copied!

Best PracticesCopied!

1. Split large catalogs - For very large catalogs, split imports into batches of 10,000 products or fewer
2. Include complete data - Provide as much product information as possible for optimal AI performance
3. Use high-quality images - Include multiple high-resolution images for each product
4. 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.