API Reference › Copilot › Shopping cards

Shopping cards

Structured product cards that cloro extracts whenever Microsoft Copilot surfaces shopping or commercial results, complete with pricing, seller, and rating details.

POST https://api.cloro.cloud/v1/copilot

Overview

Shopping cards are not fetched through a dedicated call. They arrive as part of the standard Copilot extraction response whenever the underlying answer includes product listings. When Copilot presents commercial content, cloro parses it into a normalized shoppingCards array so you can read product data programmatically without scraping the rendered page.

No extra flags or parameters are needed to opt in — if product cards are present in the Copilot answer, they are populated automatically. When Copilot returns no commercial results, the array is simply omitted or empty.

Shopping card structure

Every entry in the shoppingCards array groups a set of related products under a shared presentation style.

Field	Type	Description
type	string	Category of the card, for example `shoppingProducts`.
layout	string	How the products are laid out, such as `Carousel`.
products	array	Collection of individual product objects contained in this card.

Product information

Each object in the products array describes a single offering.

Field	Type	Description
product	object	Identifier block carrying `id`, `groupId`, and `brandGroupId`.
position	integer	1-based rank of the product across every shopping card in the response; the counter is flat and does not restart per card.
offerId	string	Identifier that uniquely marks this specific offer.
url	string	Link to the product's detail page.
name	string	Display name of the product.
description	string	Short text summarizing the product.
images	array	Image entries, each with a `title` and `url`.
specifications	array	Attribute entries, each pairing a `displayName` with one or more `values`.
tags	array	Descriptive labels attached to the product.
price	object	Current price block (see below).
discountPrice	object	Reduced price using the same shape as `price`; `null` when there is no discount.
seller	string	Name of the merchant offering the product.
sellerLogoUrl	string	URL of the seller's logo image.
brandName	string	Brand the product belongs to.
rating	object	Aggregate rating block (see below).
canTrackPrice	boolean	Indicates whether price tracking can be enabled for this product.

Product identifier structure

The nested product field holds the identifiers cloro uses to reference the item.

Field	Type	Description
id	string	Unique product identifier.
groupId	string	Identifier for the product group.
brandGroupId	string	Optional identifier for the brand-level group.

Price structure

Field	Type	Description
amount	number	Numeric price value.
currency	string	ISO currency code; optional.
currencySymbol	string	Symbol for the currency, for example `$`.

Rating structure

Field	Type	Description
value	number	Average rating score.
count	integer	Total number of ratings collected.
maxRating	number	Top of the rating scale; may be `null`.

Response example

{
  "success": true,
  "result": {
    "text": "Here are several laptops well suited to software development...",
    "shoppingCards": [
      {
        "type": "shoppingProducts",
        "layout": "Carousel",
        "products": [
          {
            "product": {
              "id": "prod_12345",
              "groupId": "group_12345"
            },
            "position": 1,
            "offerId": "offer_12345",
            "url": "https://www.microsoft.com/en-us/d/surface-laptop-studio-2/8rqr54krf1dz",
            "name": "Microsoft Surface Laptop Studio 2",
            "description": "High-performance laptop aimed at developers and creators",
            "images": [
              { "title": "Front view", "url": "https://cdn.example.com/surface-front.jpg" }
            ],
            "specifications": [
              { "displayName": "Color", "values": ["Platinum", "Black"] }
            ],
            "tags": ["laptop", "professional"],
            "price": {
              "amount": 1999.99,
              "currency": "USD",
              "currencySymbol": "$"
            },
            "discountPrice": null,
            "seller": "Microsoft Store",
            "sellerLogoUrl": "https://cdn.example.com/microsoft-logo.png",
            "brandName": "Microsoft",
            "rating": {
              "value": 4.7,
              "count": 542,
              "maxRating": 5
            },
            "canTrackPrice": true
          }
        ]
      }
    ]
  }
}

Notes

The position value spans the whole response, so a product in the second card continues the numbering from the first rather than restarting at one.
Optional fields such as discountPrice, brandGroupId, and maxRating may be null or absent depending on what Copilot exposes for a given query.
Questions about response shapes can be sent to [email protected].