API Reference › AI Mode › Shopping cards

Shopping cards

Structured product listings that appear inside a Perplexity response whenever cloro detects that the prompt carries shopping intent.

Overview

Shopping cards are not a separate request. They are emitted as part of the normal Perplexity response, so you never call a dedicated route to obtain them. When a prompt looks like a purchase or product-discovery query — for example asking for recommendations, price ranges, or where to buy something — cloro attaches a shopping_cards array to the result. Each card groups related products, and every product carries pricing, ratings, imagery, and merchant offers.

No special flag is needed. Simply issue a Perplexity request whose prompt expresses shopping intent, and the cards are included automatically when relevant.

Example request

{
  "prompt": "best running shoes under $150",
  "country": "US"
}

A prompt like this yields a response whose result object contains the shopping_cards array described below.

Shopping card structure

The top-level container lives on the result object.

Field	Type	Description
result.shopping_cards	array	Collection of product cards returned for a shopping-intent prompt

Each entry in the array is a single card:

Field	Type	Description
products	array	List of product objects belonging to this card
tags	array	Optional category labels describing the grouping

Product structure

Every object inside a card's products array uses the following shape.

Field	Type	Description
title	string	Display name of the product
position	integer	1-indexed rank across every product in every card of the response; the counter is flat and does not restart per card
url	string	Link to the product's detail page
description	string	Short summary of the product
price	string	Current listed price
original_price	string	Pre-discount price, or null when no discount applies
rating	number	Average rating on a 0–5 scale
numReviews	number	Count of reviews backing the rating
imageUrls	array	One or more image links for the product
merchant	string	Name of the seller
id	any	Identifier assigned to the product
variants	array	Alternate options such as size or color
offers	array	Individual seller offers, each with its own merchant, price, and link

Response example

{
  "success": true,
  "result": {
    "text": "Here are several running shoes under $150...",
    "shopping_cards": [
      {
        "tags": ["running", "athletic"],
        "products": [
          {
            "title": "Nike Pegasus 41",
            "position": 1,
            "url": "https://www.nike.com/t/pegasus-41",
            "description": "Responsive cushioning for daily training runs.",
            "price": "$140.00",
            "original_price": null,
            "rating": 4.6,
            "numReviews": 1284,
            "imageUrls": ["https://static.nike.com/pegasus-41.jpg"],
            "merchant": "Nike",
            "id": "nike-pegasus-41",
            "variants": [],
            "offers": [
              {
                "merchant": "Nike",
                "price": "$140.00",
                "url": "https://www.nike.com/t/pegasus-41"
              }
            ]
          }
        ]
      }
    ]
  }
}

Notes

The shopping_cards array is only present when a shopping intent is detected; ordinary informational prompts return a response without it. Because position is numbered continuously across all cards, you can flatten every product into a single ranked list without recomputing order. If you run into questions about the shape of these results, reach us at [email protected].