Render Products Response

Normalized ACP Engine response that asks the frontend to render product cards or a product carousel.

What This Example Demonstrates

The RENDER_PRODUCTS action tells the client that the response contains structured products, not only assistant text. The frontend can render a carousel, grid, or accessible list from data.products while keeping the assistant's content as the conversational introduction.

How to Read the Response

Use stable product and SKU identifiers for selection events. Treat price and inventory as display-time values that may need confirmation before checkout. Provider, token, cost, and trace fields are operational metadata and should not be shown as customer-facing product content.

If the client does not support RENDER_PRODUCTS, it should fall back to a readable text or list representation rather than discarding the response.

{
  "status": 200,
  "body": {
    "action": "RENDER_PRODUCTS",
    "content": "I found a few good options. You can review details or add one to your cart.",
    "session_id": "{{session_id}}",
    "provider": {
      "name": "chat-completions provider",
      "model": "gpt-4.1-mini"
    },
    "token_usage": {
      "prompt_tokens": 1840,
      "completion_tokens": 220,
      "total_tokens": 2060
    },
    "cost": {
      "currency": "USD",
      "estimated": "0.0018"
    },
    "data": {
      "source": "merchant_services_products",
      "query": "black waterproof jacket",
      "products": [
        {
          "id": "prd_01HX7JACKETBLACK",
          "scope": {
            "merchantId": "{{merchant_id}}",
            "storeId": "{{store_id}}"
          },
          "productId": "1234567890",
          "sku": "JACKET-BLK-M",
          "externalId": "shopify_product_1001",
          "name": "Black Waterproof Hiking Jacket",
          "brand": "Example Brand",
          "description": "Lightweight waterproof shell with adjustable hood and sealed seams.",
          "price": 129.9,
          "original_price": 159.9,
          "price_text": "$129.90",
          "currency": "USD",
          "url": "https://store.example.com/products/black-waterproof-hiking-jacket",
          "image": "https://cdn.example.com/products/jacket-black-main.jpg",
          "in_stock": true,
          "inventoryQuantity": 18,
          "storeName": "Example Brand Store",
          "images": [
            {
              "image": "https://cdn.example.com/products/jacket-black-main.jpg",
              "order": 1
            },
            {
              "image": "https://cdn.example.com/products/jacket-black-side.jpg",
              "order": 2
            }
          ],
          "variants": [
            {
              "attribute_name": "Color",
              "attribute_key": "color",
              "options": [
                {
                  "label": "Black",
                  "value": "black",
                  "is_selected": true,
                  "in_stock": true
                }
              ]
            },
            {
              "attribute_name": "Size",
              "attribute_key": "size",
              "options": [
                {
                  "label": "S",
                  "value": "S",
                  "is_selected": false,
                  "in_stock": true,
                  "product": {
                    "pk": 10011
                  }
                },
                {
                  "label": "M",
                  "value": "M",
                  "is_selected": true,
                  "in_stock": true,
                  "product": {
                    "pk": 10012
                  }
                },
                {
                  "label": "L",
                  "value": "L",
                  "is_selected": false,
                  "in_stock": false,
                  "product": {
                    "pk": 10013
                  }
                }
              ]
            }
          ]
        },
        {
          "id": "prd_01HXRAINPARKA",
          "productId": "1234567891",
          "sku": "PARKA-BLK-L",
          "externalId": "shopify_product_1002",
          "name": "Storm Shield Rain Parka",
          "brand": "Example Brand",
          "description": "Long waterproof parka with breathable lining.",
          "price": 179,
          "original_price": 179,
          "price_text": "$179.00",
          "currency": "USD",
          "url": "https://store.example.com/products/storm-shield-rain-parka",
          "image": "https://cdn.example.com/products/parka-black-main.jpg",
          "in_stock": true,
          "inventoryQuantity": 7,
          "storeName": "Example Brand Store",
          "images": [],
          "variants": []
        }
      ]
    },
    "trace_id": "trace_01HX7W9Y8V4N2R2N"
  }
}