Products

List Merchants

Changed on Nov 3, 2026

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.

post/products/merchants

Request

Base URL
https://api.peec.ai/customer/v1
URL
https://api.peec.ai/customer/v1/products/merchants
Auth
- API key in header X-API-Key
- or API key in query parameter api_key
- or HTTP bearer

Request body

project_idstring

Required if using a company api key

start_datestring date

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

end_datestring date

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

category_idsstring[]

Filter by shopping categories. Parent categories include descendants.

country_codesstring[]

model_channel_idsstring[]

topic_idsstring[]

tag_idsstring[]

tag_operator'and' | 'or'

previous_start_datestring 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_datestring date

End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.

merchant_idsstring[]

Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator.

product_idsstring[]

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'

limitinteger

offsetinteger

Example request

{
  "project_id": "or_f45b94ba-5e35-4982-93ed-285e72ee14eb",
  "start_date": "2025-09-22",
  "end_date": "2025-09-22"
}

Response

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.

total_countnumber required

Changes

Nov 3, 20269d774600c8eb Revision changes
- info
  added the new exa-0 enum value to the request property / (media type: application/json)
- info
  added the new exa-0 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new exa-0 enum value to the request property / (media type: multipart/form-data)
Nov 3, 20269fdffdff48a5 Revision changes
- info
  added the new anthropic-2 enum value to the request property / (media type: application/json)
- info
  added the new anthropic-2 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new anthropic-2 enum value to the request property / (media type: multipart/form-data)
- info
  added the new anthropic-3 enum value to the request property / (media type: application/json)
- info
  added the new anthropic-3 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new anthropic-3 enum value to the request property / (media type: multipart/form-data)
- info
  added the new baidu-0 enum value to the request property / (media type: application/json)
- info
  added the new baidu-0 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new baidu-0 enum value to the request property / (media type: multipart/form-data)
- info
  added the new google-5 enum value to the request property / (media type: application/json)
- info
  added the new google-5 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new google-5 enum value to the request property / (media type: multipart/form-data)
- info
  added the new meta-1 enum value to the request property / (media type: application/json)
- info
  added the new meta-1 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new meta-1 enum value to the request property / (media type: multipart/form-data)
- info
  added the new meta-2 enum value to the request property / (media type: application/json)
- info
  added the new meta-2 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new meta-2 enum value to the request property / (media type: multipart/form-data)
- info
  added the new naver-0 enum value to the request property / (media type: application/json)
- info
  added the new naver-0 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new naver-0 enum value to the request property / (media type: multipart/form-data)
- info
  added the new openai-3 enum value to the request property / (media type: application/json)
- info
  added the new openai-3 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new openai-3 enum value to the request property / (media type: multipart/form-data)
- info
  added the new openai-4 enum value to the request property / (media type: application/json)
- info
  added the new openai-4 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new openai-4 enum value to the request property / (media type: multipart/form-data)
- info
  added the new openai-5 enum value to the request property / (media type: application/json)
- info
  added the new openai-5 enum value to the request property / (media type: application/x-www-form-urlencoded)
- info
  added the new openai-5 enum value to the request property / (media type: multipart/form-data)

Operation history