---
title: "List Merchants"
method: POST
path: "/products/merchants"
tags: ["Products"]
---

# List Merchants

`POST /products/merchants`

List the merchants (sellers) whose product offers surfaced in AI answers, ranked over a date range: mentions, share of voice against the other merchants, buy-box win rate, average position, and average star rating, each with a delta against the previous window. Scope the population with category_ids or product_ids to get per-category or per-product seller breakdowns.

## 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[] — Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator.
  - `product_ids` string[] — Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers.
  - `order_by` 'mention_count' | 'win_rate' | 'avg_rating' | 'avg_position'
  - `direction` 'asc' | 'desc'
  - `limit` integer
  - `offset` integer

## Response `200`

Merchants (sellers) ranked by their metrics over the date range, with deltas against the previous window. share_of_voice divides a merchant's mentions by all merchants' mentions in the filtered population, so category_ids/product_ids give per-category or per-product seller shares. win_rate is the buy-box rate (position-1 mentions over all mentions). Only merchants with current-window mentions are returned.

- object — Merchants (sellers) ranked by their metrics over the date range, with deltas against the previous window. share_of_voice divides a merchant's mentions by all merchants' mentions in the filtered population, so category_ids/product_ids give per-category or per-product seller shares. win_rate is the buy-box rate (position-1 mentions over all mentions). Only merchants with current-window mentions are returned.
  - `data` object[], required
    - `merchant_id` string, uuid, required
    - `name` string, required
    - `domain` string, required
    - `mention_count` number, required
    - `mention_count_delta` number, required
    - `share_of_voice` number, required
    - `share_of_voice_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
    - `avg_rating` number, nullable, required
    - `avg_rating_delta` number, nullable, 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/revisions/92840a1bffa7/schema)