Check Moderation Results

Use the product list to retrieve the current moderation result for every product. Catalogue scope is derived automatically, so you do not need a catalogue ID or a separate moderation-result download endpoint.

Moderation runs independently from product ingestion. A completed processStatus does not guarantee that moderation.status is terminal.

1. Retrieve Products

Create a fresh single-use product:read token as shown in Upload Product Data and Track Processing, then use it once:

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

Fetch pages 1 through meta.totalPages, creating another token for every page and retry. Each product's moderation field contains the current result for the active ruleset; it is not a history of earlier runs or ruleset versions.

To request only a supported moderation subset, add moderation_status:

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

The accepted filter values are lifecycle values approved, pending, and flagged, or exact violation severities high, medium, and low. These filters match current per-stage results; they are not a completeness check or strict aggregate-status comparison. Always use the unfiltered list when deciding whether every applicable stage has finished.

2. Read the Aggregate Result

moderation is null or absent until the product has a current moderation result. When present, it has this shape:

{
  "status": "flagged",
  "violations": [
    {
      "slug": "title-format",
      "ruleVersion": 3,
      "severity": "medium",
      "evidence": "The title contains unsupported promotional text",
      "sourcePass": "screen"
    }
  ],
  "passedSlugs": ["description-present"],
  "reviewStatus": "pending",
  "unpublishApplied": false,
  "rulesetVersion": "3",
  "rulesetId": "c1f3f8c7-61e5-4aba-a52f-d850df3a789c",
  "updatedAt": "2026-08-10T12:00:00.000Z",
  "stageResults": [
    {
      "dataStage": "original",
      "status": "approved",
      "violations": [],
      "passedSlugs": ["title-format", "description-present"],
      "reviewStatus": "none",
      "unpublishApplied": false,
      "imageUrls": []
    },
    {
      "dataStage": "images",
      "status": "flagged",
      "violations": [
        {
          "slug": "watermark",
          "ruleVersion": 2,
          "severity": "high",
          "evidence": "A promotional watermark is visible",
          "sourcePass": "confirm",
          "imageIndex": 0
        }
      ],
      "passedSlugs": [],
      "reviewStatus": "pending",
      "unpublishApplied": false,
      "imageUrls": ["https://cdn.example.com/moderation/chair-001.jpg"]
    }
  ]
}

Interpret the aggregate status as a summary:

Do not use the aggregate status alone to decide that moderation is finished. In particular, flagged takes precedence as a summary even when another stage is still pending or processing.

reviewStatus is separate from the moderation lifecycle. It is none when there is no flagged stage, pending while flagged results await review, approved when all flagged results were approved, or rejected when a flagged result was rejected and none remain pending. unpublishApplied reports whether a moderation action was applied to publication state.

3. Inspect Per-Stage Results

Use moderation.stageResults to see which form of product data produced a result. Only applicable stages appear, so key results by dataStage rather than array position:

Every stage result has its own status, violations, passedSlugs, reviewStatus, unpublishApplied, ruleset identifiers, and update time. Image-stage results can include public imageUrl or imageUrls; private storage references are never returned.

Each violation can include:

passedSlugs lists rules that passed for the aggregate or stage result.

4. Decide When Moderation Is Finished

For a submitted upload, reconcile every submitted SKU against variants[].offers[].sku in the product list. Deduplication can place several SKUs under one product, so evaluate the moderation result on that containing product.

For each containing product, first require a non-null moderation result. Moderation is finished only when every applicable entry in moderation.stageResults has a terminal status:

• Terminal: approved, flagged, error, or skipped.
• Not terminal: pending or processing.

The submitted data is moderation-complete when this per-stage rule holds for every submitted SKU. Treat terminal flagged and error stage results as outcomes that require attention; do not keep polling for them to become approved automatically.

For moderation administration and manual review workflows, see Product Moderation. Reading current results through GET /api/v1/product does not require those administration routes.

Relevant Errors

• 400 means a product-list filter is invalid.
• 401 means the bearer token is missing, invalid, expired, outside product:read scope, or already consumed.
• 403 means the product request is not permitted.
• 502 means the product service was unavailable or returned an invalid response. Create a fresh token before retrying.