Upload Product Data and Track Processing

Use this guide to upload product data and follow it through the ingestion pipeline. The API derives catalogue scope automatically; you do not need a catalogue ID.

The upload workflow is:

Submit product data with the API key.
Create a single-use product:read token.
Fetch every page of GET /api/v1/product and inspect each product's processing state.

Keep the API key on your server. Never put it in browser code, a mobile application, source control, or a product-data file.

Before You Start

Set the API base URL and client key in your server-side environment:

export YOUZU_API_BASE="https://platform.youzu.ai"
export YOUZU_CLIENT_KEY="YOUR_CLIENT_KEY"

Prepare every record according to the Product Data Requirements, and keep the complete set of submitted SKUs. Processing can merge several SKUs into one product, so those SKUs are the reliable way to track your upload.

1. Submit Product Data

Both ingestion methods use the catalogue-free endpoint:

POST /api/v1/admin/catalogue/ingest
x-client-key: YOUR_CLIENT_KEY
Content-Type: application/json

Use Real-time Catalogue Import to send product objects in a products array.
Use API Batch Import to submit a hosted CSV, JSON, or XML feed.

Do not send clientId, catalogueId, or externalRef. Youzu derives the account and catalogue scope and creates the external reference.

A 200 response means the asynchronous ingestion request was accepted. It does not mean image download, AI enrichment, indexing, or deduplication has finished. Product records returned by the list endpoint are the source of truth for current progress.

2. Create a Product Read Token

Create a token immediately before each product-list request:

POST /api/v1/token
x-client-key: YOUR_CLIENT_KEY
Content-Type: application/json

{
  "actionResource": "product",
  "actionType": "read"
}

The API derives catalogue scope from the key. The token is valid for five minutes and is consumed by one protected request. Create a fresh token for every page, polling request, or retry.

See Authentication for the complete token contract.

3. Retrieve Every Product Page

Use the token once to request a page:

curl "$YOUZU_API_BASE/api/v1/product?page=1&limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response contains complete current product records in data and pagination information in meta. Request pages 1 through meta.totalPages, creating a fresh token before each request. Repeat the full pagination pass when polling so products created or merged during processing are not missed.

The product list is also the download interface for source data, AI enrichment, images, variants, nested offers, processing details, and current moderation results. See Product Management for the complete response and filter reference.

4. Understand Processing State

processStatus summarizes the product-ingestion pipeline:

Value	Meaning	Terminal
`pending`	Nonterminal coarse state; early or middle ingestion stages may already be complete	No
`processing`	Nonterminal coarse state used for later pipeline work or active reprocessing	No
`completed`	All ingestion stages completed successfully	Yes
`failed`	Processing stopped with a failure that requires attention	Yes

Do not infer exact stage progress from processStatus. Use the processing object for stage-level progress:

Stage	Meaning
`ingest`	Product metadata was accepted
`images`	Source images were downloaded and stored
`enrichment`	AI enrichment was applied
`indexing`	Vector-search data was written
`dedup`	Duplicate and variant relationships were evaluated

Use processing.currentStage for the first incomplete stage, completedStages and totalStages for a progress summary, and processing.stages[].done for each stage's current result.

Moderation is a separate lifecycle. A product can have processStatus: completed while moderation is still pending. After checking processing, follow Check Moderation Results.

5. Decide When the Upload Is Processed

Evaluate only the SKUs from the upload you submitted:

Find each SKU under variants[].offers[].sku; do not rely only on the top-level product.sku, which represents one offer.
Deduplication can merge several submitted SKUs into variants and offers under one product. meta.totalItems can therefore be lower than the submitted SKU count.
Treat a submitted SKU as processed when its containing product has processStatus completed or failed.
Treat failed as terminal but unsuccessful. Record the affected SKU and product for investigation instead of waiting for it to become completed automatically.

The upload's processing phase is finished when every submitted SKU is present and its containing product has a terminal processStatus. This does not imply that moderation has finished.

Relevant Errors

400 from ingestion means the product data or ingestion source is invalid.
401 means the API key or bearer token is missing, invalid, expired, outside the required scope, or already consumed.
404 from token creation or ingestion means the key has no enabled catalogue.
409 means the key resolves to more than one enabled catalogue; contact support.
413 means the JSON request or upstream ingestion payload is too large.
429 means ingestion is temporarily rate limited; retry later.
502 means the product or ingestion service was unavailable. Create a fresh token before retrying a product-list request.

Authentication

Check moderation results