Skip to main content
POST
/
products
/
ai
/
description
AI Product Description
curl --request POST \
  --url https://staging-api.puppetvendors.com/products/ai/description \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "title": "<string>",
  "productType": "<string>",
  "tags": [
    "<string>"
  ],
  "features": [
    "<string>"
  ],
  "imageContext": "<string>",
  "merchantCustomPrompt": "<string>"
}
'
V2 Preview — This endpoint is part of the V2 API preview. Breaking changes may occur.

​
Overview

Generate an HTML product description using AI. Provide the product title and optional context (product type, tags, features, image context) to get a ready-to-use description. The merchant can also configure a custom prompt that shapes the AI output to match their brand voice. Usage is subject to the shop’s AI allowance limit. If the limit is reached, you will receive a 429 response.

​
Use Cases

  • Auto-generate descriptions for new products instead of writing from scratch
  • Improve or rewrite existing descriptions with richer detail
  • Create consistent, on-brand copy across your catalog

​
Required Scope

products:write

​
Request Body

​
title
string
required
The product title. This is the primary input the AI uses to generate the description.
​
productType
string
The product type or category (e.g. “T-Shirts”, “Electronics”). Helps the AI tailor the description.
​
tags
string[]
An array of product tags (e.g. ["organic", "cotton", "summer"]). Provides additional context for the AI.
​
features
string[]
An array of key product features (e.g. ["100% organic cotton", "Pre-shrunk", "Machine washable"]). These are highlighted in the generated description.
​
imageContext
string
A text description of the product’s main image. Useful when the AI cannot see the image directly.
​
merchantCustomPrompt
string
A custom instruction from the merchant that shapes the AI output (e.g. “Write in a casual, friendly tone” or “Always mention our 30-day return policy”). This is configured at the shop level and passed through automatically by the portal.

​
Response

200
{
  "success": true,
  "data": {
    "description": "<p>Elevate your everyday wardrobe with our Organic Cotton Tee. Crafted from 100% certified organic cotton, this pre-shrunk tee offers a soft, breathable fit that lasts wash after wash.</p><ul><li>100% organic cotton</li><li>Pre-shrunk for a consistent fit</li><li>Machine washable</li></ul><p>Perfect for layering or wearing on its own during the warmer months.</p>"
  }
}
429
{
  "success": false,
  "error": {
    "message": "AI usage limit reached. Please try again later.",
    "code": "ALLOWANCE_EXCEEDED"
  }
}

​
Example

curl -X POST "https://staging-api.puppetvendors.com/products/ai/description" \
  -H "x-access-token: YOUR_VENDOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Organic Cotton Tee",
    "productType": "T-Shirts",
    "tags": ["organic", "cotton", "summer"],
    "features": ["100% organic cotton", "Pre-shrunk", "Machine washable"],
    "imageContext": "A white t-shirt on a wooden hanger against a neutral background"
  }'

​
More Examples

With features and merchant prompt 
curl -X POST "https://staging-api.puppetvendors.com/products/ai/description" \
  -H "x-access-token: YOUR_VENDOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Organic Cotton Hoodie",
    "productType": "Apparel",
    "tags": ["organic", "sustainable"],
    "features": ["100% organic cotton", "Relaxed fit", "Kangaroo pocket"],
    "merchantCustomPrompt": "Write in a casual, friendly tone. Emphasize sustainability."
  }'