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 category 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.

category is optional and is different from the required catalogueId. It replaces the former categoryId request field. Use {"category":{"id":"11111111-1111-4111-8111-111111111111"}} for a Youzu category UUID or {"category":{"<SLUG_KEY>":"<SLUG_VALUE>"}} to match category_slug[<SLUG_KEY>] = <SLUG_VALUE>. Replace both placeholders with the category's exact configured key and value. Supply exactly one key: either id or one configured slug key/value pair. Multiple slug pairs or an ID plus a slug return 422. id is reserved for a Youzu UUID. Slug keys are independent of catalogue languages.

category.id uses the category UUID from your catalogue. catalogueId uses the catalogue UUID.

A matched leaf skips category inference; a parent limits selection to its descendants. If the selector is omitted or no unique category matches, Gemini selects from the supplied product evidence. Invalid selectors return 422. Reuse the resolved category on later requests; see Select a product category for matching and fallback.

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 category. 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 v1-compatible 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.

Every catalogue-rule image finding contains the exact request image reference it applies to. If one rule affects multiple images, the images array contains one finding per offending image, repeating the policy with a different reference.

Category and attribute example

Pass the selected category 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",
    "category": {"id": "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": {"<SLUG_KEY>": "<SLUG_VALUE>"}
  }],
  "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 category UUIDs, 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.