Upload Product Data and Track Processing

Use this guide to upload product data and follow it through the ingestion pipeline. Accounts with one enabled catalogue can let the API derive catalogue scope. Accounts with multiple enabled catalogues must use the explicit catalogue route and catalogue-scoped tokens.

The upload workflow is:

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

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

With exactly one enabled catalogue, both ingestion methods can 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.

With multiple enabled catalogues, use POST /api/v1/admin/catalogue/{catalogueId}/ingest with the same body. Do not send clientId, catalogueId, or externalRef inside the body. Youzu derives the account from the key, verifies ownership of the path catalogue, 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",
  "catalogueId": "YOUR_CATALOGUE_ID"
}

catalogueId may be omitted only when the key resolves to exactly one enabled catalogue supporting product reads. 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 selected product-ingestion plan:

Do not infer exact progress from processStatus. Use the processing object. It contains an explicit record for each stage in the catalogue's compiled, selected pipeline graph:

Each processing.stages[] item has:

• key: the stable stage identifier.
• status: pending, processing, completed, skipped, or failed.
• required: whether the catalogue's immutable feature selection requires that stage.
• attemptCount: how many times the stage has been attempted.

Stages outside the compiled graph are absent. A returned stage can use status: "skipped" when runtime processing determines that no work is needed. Use processing.currentStage for the active required stage and completedStages/totalStages for a coarse progress summary.

processing.errors is an array of sanitized failures. Each item contains only code, stage, and retryable; internal provider messages, URLs, and traces are never returned. A partial product can therefore have one or more errors while still exposing successful output from other selected stages.

Moderation is a separate lifecycle. When a catalogue includes moderation, a product can have processStatus: completed or partial while moderation is still pending. Follow Check Moderation Results after evaluating processing.

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, partial, or failed.
• Treat partial as terminal with usable output plus failed selected stages. Record processing.errors and decide whether retry is appropriate.
• Treat failed as terminal and unsuccessful. Record the affected SKU and product for investigation.

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 catalogue-free token creation or ingestion means no enabled compatible catalogue could be resolved.
• 409 means catalogue scope is ambiguous or the selected catalogue does not support the requested action. Use an explicit catalogue ID when the account has multiple enabled catalogues.
• 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.