Merchant API v1

Use v1 when your integration expects the original Merchant API response contract: flat result arrays with top-level status, sections, and errors. New integrations should use Merchant API v2, whose component objects make partial results easier to handle.

Both versions accept the same current request fields. v1 therefore supports the latest product context and optional categoryId without changing its existing response shape. Calls are advisory and do not create, update, or publish catalogue products.

Authenticate and select a catalogue

Send the reusable customer API key in x-client-key and the target catalogue UUID as catalogueId in every JSON request body:

x-client-key: YOUR_CLIENT_KEY
Content-Type: application/json

The API key identifies the client. catalogueId selects one of that client's enabled, ready catalogues with Merchant API access. Do not mint a token or use bearer or x-token authentication for these routes.

categoryId is an optional category UUID inside the selected catalogue. If a merchant already chose a category, pass its id in later category, attribute, and description requests. A leaf is used directly; a parent limits selection to its descendants. Omit it when the category should be inferred. categoryId is optional and is not the same field as the required catalogueId.

Endpoints and requests

The base path is https://platform.youzu.ai/api/v1/merchant-api.

All five analysis endpoints accept the same optional product context: language-keyed name and description, brand, attributes, images, and categoryId. You can send the complete current product draft. The attributes object accepts any current product facts; it is not limited to the selected category's configured keys. Image moderation still requires images.

For field limits and complete request examples, see the corresponding endpoint in the v2 guide. Only the response envelope differs.

Understand v1 responses

Every successful analysis response has this structure:

{
  "status": "complete",
  "sections": {
    "category": "complete",
    "attributes": "complete",
    "localization": "complete"
  },
  "category": [],
  "attributes": [],
  "errors": []
}

status is complete only when every section is complete; otherwise it is partial.

The operation determines which section and result keys are present:

Each error has code, section, retryable, and localized messages. Use retryable to decide whether another request is appropriate. A content mismatch is an advisory warning represented in the legacy shape with code: "CONTENT_MISMATCH" and section: "input". It does not make otherwise complete sections partial. The v1 error shape cannot identify individual request paths; use v2 if your UI needs that detail.

Category and attribute example

Pass the selected categoryId to keep later suggestions tied to the merchant's choice:

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/attributes/suggestions \
  -H "x-client-key: YOUR_CLIENT_KEY" -H "Content-Type: application/json" \
  -d '{
    "catalogueId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryId": "11111111-1111-4111-8111-111111111111",
    "name": {"en": "Black Running Shoe"},
    "attributes": {"season": "summer"}
  }'

{
  "status": "complete",
  "sections": {
    "category": "complete",
    "attributes": "complete",
    "localization": "complete"
  },
  "category": [{
    "id": "11111111-1111-4111-8111-111111111111",
    "label": {"en": "Running shoes"},
    "breadcrumb": [{"en": "Footwear"}, {"en": "Running shoes"}],
    "category_slug": {"en": "RUNNING_SHOES"}
  }],
  "attributes": [{
    "key": "waterproof",
    "label": {"en": "Waterproof"},
    "value": [{"en": false}],
    "attribute_slug": {"en": "WATERPROOF"},
    "attribute_value_slug": [{"en": "NO"}]
  }],
  "errors": []
}

Suggestions are ranked best first. Name, brand, and description entries contain ordered value arrays. Attribute value is an ordered array of localized maps; numeric 0 and boolean false keep their JSON types. Category results contain catalogue IDs, localized labels, root-to-leaf breadcrumbs, and optional customer slugs.

Content mismatch example

{
  "status": "complete",
  "sections": {
    "images": "complete",
    "image_rules": "complete",
    "localization": "complete"
  },
  "images": [],
  "errors": [{
    "code": "CONTENT_MISMATCH",
    "section": "input",
    "retryable": false,
    "messages": {"en": "The product name may not match the supplied image."}
  }]
}

Treat the mismatch as a warning for the merchant. It is not an HTTP failure and does not discard usable results.

Upload an image

POST /assets/upload-url uses the same request and upload procedure in both versions. Its v1 response additionally contains sections: {"asset_upload": "complete"}. See Upload a Youzu Asset for the complete handoff.

Move to v2

Request fields and paths after the version prefix stay the same. Change /api/v1/ to /api/v2/ and update response parsing as follows:

Authentication, catalogue ownership checks, entitlements, capability checks, and quotas do not change between versions.