Product Optimizations API

Last updated: March 27, 2026

Generate AI-optimized product descriptions from review data and publish them to Shopify. The optimization workflow is: start → poll → edit (optional) → approve → publish.

Note: Product IDs in these endpoints are internal BetterReviews IDs, not Shopify IDs. Use GET /products/lookup/:platform_id to convert a Shopify product ID first.

Start Optimization

POST /api/v1/products/:product_id/optimize

Starts an async AI optimization job. Returns immediately with status pending.

Request

{
  "feedback": "Focus on fabric quality and comfort",
  "blocksToOptimize": ["description", "features"]
}

Field	Type	Required	Description
`feedback`	string	No	Instructions for the AI (tone, focus areas, keywords)
`blocksToOptimize`	string[]	No	Specific sections to optimize

Response (202)

{
  "id": "uuid",
  "status": "pending",
  "version": 1,
  "created_at": "2026-03-27T10:00:00Z"
}

Get Current Optimization

GET /api/v1/products/:product_id/optimization

Poll this endpoint after starting an optimization to check status and get results.

Response (200)

{
  "id": "uuid",
  "version": 3,
  "status": "draft",
  "content": {
    "description": "...",
    "features": ["..."],
    "seo_title": "...",
    "seo_description": "..."
  },
  "created_at": "2026-03-27T10:00:00Z",
  "published_at": null,
  "error_message": null
}

List All Versions

GET /api/v1/products/:product_id/optimizations?limit=10&offset=0

Returns paginated list of all optimization versions for a product.

Edit Optimization

PATCH /api/v1/products/:product_id/optimization

Request

{
  "content": {
    "description": "Updated description text..."
  }
}

Regenerate

POST /api/v1/products/:product_id/optimization/regenerate

Creates a new version. Accepts same parameters as Start (feedback, blocksToOptimize).

Approve

POST /api/v1/products/:product_id/optimization/approve

Marks the optimization as approved and ready to publish.

Publish to Shopify

POST /api/v1/products/:product_id/optimization/publish

Writes the optimization content to the Shopify product metafield. The storefront updates with the new content.

Discard

DELETE /api/v1/products/:product_id/optimization

Optimization Statuses

Status	Meaning
`pending`	Processing (async job running)
`draft`	Generated, ready for review
`approved`	Merchant approved, ready to publish
`published`	Live on Shopify storefront
`failed`	Generation failed (check `error_message`)
`discarded`	Merchant discarded