---
title: "List Shopping Performance"
method: POST
path: "/products/performance"
tags: ["Products"]
---

# List Shopping Performance

`POST /products/performance`

List ranked product or category shopping performance over a date range.

## Request body

- object
  - `project_id` string — Required if using a company api key
  - `start_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `end_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `category_ids` string[] — Filter by shopping categories. Parent categories include descendants.
  - `country_codes` string[]
  - `model_channel_ids` string[]
  - `topic_ids` string[]
  - `tag_ids` string[]
  - `tag_operator` 'and' | 'or'
  - `previous_start_date` string, date — Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].
  - `previous_end_date` string, date — End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.
  - `merchant_ids` string[] — Filter to products sold through these merchants.
  - `entity_type` 'product' | 'category', required — Rank products (leaderboard) or categories.
  - `brand_ids` string[] — For products, keep only products of these global brands.
  - `product_ids` string[]
  - `category_id` string, uuid — For categories, return only this category.
  - `chat_scope` 'all' | 'shopping' — Which chats the visibility denominator counts: every in-scope chat ('all') or only product-gallery ('shopping') chats. Defaults to 'shopping'.
  - `mode` 'top' | 'trending' | 'losing' — top = highest now; trending = biggest gainers; losing = biggest losers.
  - `order_by` 'visibility' | 'win_rate' | 'appearances'
  - `direction` 'asc' | 'desc'
  - `limit` integer
  - `offset` integer

## Response `200`

Success

- object — Success
  - `data` object[], required
    - `entity_type` 'product' | 'category', required
    - `entity_id` string, required
    - `name` string, required
    - `visibility` number, required
    - `visibility_delta` number, nullable, required
    - `win_rate` number, required
    - `win_rate_delta` number, nullable, required
    - `avg_position` number, nullable, required
    - `avg_position_delta` number, nullable, required
    - `appearances` number, required
    - `appearances_delta` number, required
  - `total_count` number, required

---

[API](https://skmtc.net/peec/apis/peec-ai-customer-api.md) · [All operations](https://skmtc.net/peec/apis/peec-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/peec/peec-ai-customer-api/versions/92840a1bffa7/schema)