Merchant API

Merchant API adds optional, machine-applicable suggestions to each step of a merchant product-upload flow. Ask only for the help needed at the current step: normalize identity, choose a category, fill attributes, inspect images, or generate descriptions.

Merchant API is advisory and stateless. It does not retain drafts, products, images, suggestions, or outcomes; change a product; publish content; generate images; or decide whether a product may be published. Your application owns the current values and decides which suggestions to show or apply.

Choose an endpoint

You can change the order or omit steps. For example, an image-first flow can call image suggestions, then use those same image references with category and attribute suggestions.

Understand suggestions

A suggestion identifies one field operation or one non-modifying finding. Writable targets return at most one best suggestion from an operation.

{
  "status": "complete",
  "sections": {
    "identity": "complete",
    "localization": "complete"
  },
  "suggestions": [
    {
      "suggestion_id": "sug_1a53d99e9f8c8a6e4ca889ce8bf1df08",
      "issue_code": "TITLE_NORMALIZATION_SUGGESTED",
      "target_path": "/name/en",
      "operation": "set",
      "current_value": "Blak runing shoe",
      "proposed_value": "Black Running Shoe",
      "severity": "info",
      "reasons": {
        "en": "Corrected spelling and casing.",
        "fr": "Orthographe et casse corrigées."
      },
      "evidence": []
    }
  ],
  "errors": []
}

• target_path is a JSON-style path your application can map to a form field.
• image_reference replaces target_path for image-specific findings.
• operation is set, remove, or none. none reports advice without proposing a change.
• issue_code is stable for program logic; render reasons for people.
• reasons and generated content include every language configured on the catalogue.
• policy identifies the pinned rule ID, revision, and configured advisory action for moderation findings.
• complete, partial, and unevaluated describe what ran. Retryable failures are listed in errors while completed sections remain usable.

Responses contain only actionable suggestion fields and customer-safe findings. Do not invent a score from severity or use a suggestion as publication authority.

1. Suggest identity

Use identity suggestions as soon as the merchant supplies a title, brand, description, or image. Optional accepted category and attribute values can provide context.

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/identity/suggestions \
  -H "Authorization: Bearer YOUR_SUGGEST_IDENTITY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {"en": "Blak runing shoe"},
    "brand": "acme"
  }'

Typical writable targets are /name/{language} and /brand. Apply a set only after the merchant accepts it.

2. Suggest a category

Category suggestions consider the current text and images and return only category IDs that exist in the token-scoped catalogue taxonomy.

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/category/suggestions \
  -H "Authorization: Bearer YOUR_SUGGEST_CATEGORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {"en": "Black Running Shoe"},
    "brand": "Acme",
    "images": ["asset_v1_eyJjIjoiYWNtZSIsImciOiJob21lIiwicyI6NDgzOTIwLCJ0IjoiaW1hZ2Uvd2VicCIsInUiOiJodHRwczovL2Nkbi5leGFtcGxlLmNvbS9wcm9kdWN0cy9zaG9lLWZyb250LndlYnAifQ.XXG6dW5GHvFKCPldRL15yG2s3wHlSHe7WE5OdCrvJhg"]
  }'

If a current category is supplied, a disagreement uses CATEGORY_CONFLICT; otherwise the result uses CATEGORY_SUGGESTED. Both are advisory set operations on /category/id.

3. Suggest attributes

Accept or choose a category before requesting attributes. Merchant API loads that category's live attribute definitions and templates, then returns only keys in the category contract.

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/attributes/suggestions \
  -H "Authorization: Bearer YOUR_SUGGEST_ATTRIBUTES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": {"id": "11111111-1111-4111-8111-111111111111"},
    "name": {"en": "Black Running Shoe"},
    "brand": "Acme",
    "attributes": {"colour": "black"},
    "images": ["https://images.example.com/products/shoe-front.webp"]
  }'

Attribute operations target /attributes/{key}. A current value can produce ATTRIBUTE_CONFLICT; a missing value can produce ATTRIBUTE_SUGGESTED.

4. Review images

Image suggestions accept one to six unique HTTPS URLs or Youzu asset IDs. JPEG, PNG, and WebP images may be up to 15 MiB each.

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/images/suggestions \
  -H "Authorization: Bearer YOUR_SUGGEST_IMAGES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "asset_v1_eyJjIjoiYWNtZSIsImciOiJob21lIiwicyI6NDgzOTIwLCJ0IjoiaW1hZ2Uvd2VicCIsInUiOiJodHRwczovL2Nkbi5leGFtcGxlLmNvbS9wcm9kdWN0cy9zaG9lLWZyb250LndlYnAifQ.XXG6dW5GHvFKCPldRL15yG2s3wHlSHe7WE5OdCrvJhg",
      "https://images.example.com/products/shoe-side.jpg"
    ],
    "category": {"id": "11111111-1111-4111-8111-111111111111"}
  }'

The response includes one inspection per reference and image-specific findings for decoding, format, resolution, darkness, blur, framing or cutoff, and configured image rules. Findings use operation: "none"; Merchant API does not edit or replace an image.

Remote URLs are protected against private and link-local hosts, unsafe redirects, DNS rebinding, oversized payloads, MIME mismatches, decompression bombs, and excessive dimensions. A mixed set can return partial: usable image inspections remain available while failures appear in errors.

If an image is not already available at a public HTTPS URL, follow Upload a Youzu Asset, then pass the returned asset_id to the suggestion endpoint.

5. Suggest descriptions

Description suggestions require an accepted category and at least one accepted fact. They use the available identity, attributes, image evidence, and catalogue description template.

curl -X POST https://platform.youzu.ai/api/v1/merchant-api/descriptions/suggestions \
  -H "Authorization: Bearer YOUR_SUGGEST_DESCRIPTIONS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": {"id": "11111111-1111-4111-8111-111111111111"},
    "name": {"en": "Black Running Shoe"},
    "brand": "Acme",
    "attributes": {"color": "black", "size": 9},
    "description": {"en": "Merchant-written English description."}
  }'

Every configured catalogue language appears in descriptions with origin: "supplied" or origin: "generated". Supplied content is returned unchanged and is never overwritten. Generation is atomic: if all missing languages cannot be produced, the endpoint returns a retryable 503 instead of a mixed description result.