startProductEnrichment

Requires permission products:product:update.

Start an async AI enrichment job (description, category, brand, public image candidates). Returns a jobId immediately — poll productEnrichmentJob(jobId) until COMPLETED/FAILED. Suggestion-only: writes nothing to the catalog. Meters AI credit usage when it runs. Needs the products update permission.

Errors: a failed call returns a GraphQL errors entry, not a field on the result, and data may be null or partial. Read the entry's extensions.code and message; every shape and code is in the Error reference.

Example:

GraphQL

mutation StartProductEnrichment($productId: ID!) {
  startProductEnrichment(productId: $productId) {
    status
    error
    jobId
    suggestion {
      balanceDisplay
      balanceDollars
      costDisplay
      creditsUsed
      description
      notes
    }
  }
}

cURL

curl -X POST "https://<api-host>/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data @- <<'EOF'
{
  "query": "mutation StartProductEnrichment($productId: ID!) {\n  startProductEnrichment(productId: $productId) {\n    status\n    error\n    jobId\n    suggestion {\n      balanceDisplay\n      balanceDollars\n      costDisplay\n      creditsUsed\n      description\n      notes\n    }\n  }\n}",
  "variables": {
    "productId": "id"
  }
}
EOF

Variables:

{
  "productId": "id"
}

Response:

{
  "data": {
    "startProductEnrichment": {
      "status": "COMPLETED",
      "error": "string",
      "jobId": "id",
      "suggestion": {
        "balanceDisplay": "string",
        "balanceDollars": "string",
        "costDisplay": "string",
        "creditsUsed": 0,
        "description": "string",
        "notes": "string"
      }
    }
  }
}

startProductEnrichment(
  depth: EnrichmentDepth = STANDARD
  productId: ID!
): EnrichmentJob!

Arguments

startProductEnrichment.depth ● EnrichmentDepth enum

How deep the enrichment goes. Omit for the default.

startProductEnrichment.productId ● ID! non-null scalar

The ID of the product.

Type

EnrichmentJob object

An async product-enrichment job. Returned immediately by startProductEnrichment; poll productEnrichmentJob(jobId) until status is COMPLETED (read suggestion) or FAILED (read error). Replaces the request-blocking enrichProduct path, which exceeded the client HTTP timeout.