> ## Documentation Index > Fetch the complete documentation index at: https://docs.peec.ai/llms.txt > Use this file to discover all available pages before exploring further. # List 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. ## OpenAPI ````yaml https://api.peec.ai/customer/v1/openapi/json post /products/merchants openapi: 3.0.3 info: title: Peec AI Customer API description: Development documentation version: 1.0.0 contact: name: Peec AI Team email: support@peec.ai servers: - url: https://api.peec.ai/customer/v1 security: [] paths: /products/merchants: post: tags: - Products summary: List Merchants description: >- 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. operationId: postProductsMerchants requestBody: required: true content: application/json: schema: type: object properties: project_id: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string start_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ end_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ category_ids: description: >- Filter by shopping categories. Parent categories include descendants. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ country_codes: type: array items: type: string model_channel_ids: type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - google-4 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 - mistral-0 - mistral-1 topic_ids: type: array items: type: string tag_ids: type: array items: type: string tag_operator: type: string enum: - and - or previous_start_date: description: >- 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]. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ previous_end_date: description: >- End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ merchant_ids: description: >- Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ product_ids: description: >- Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ order_by: default: mention_count type: string enum: - mention_count - win_rate - avg_rating - avg_position direction: default: desc type: string enum: - asc - desc limit: default: 50 type: integer minimum: 1 maximum: 200 offset: default: 0 type: integer minimum: 0 maximum: 9007199254740991 application/x-www-form-urlencoded: schema: type: object properties: project_id: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string start_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ end_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ category_ids: description: >- Filter by shopping categories. Parent categories include descendants. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ country_codes: type: array items: type: string model_channel_ids: type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - google-4 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 - mistral-0 - mistral-1 topic_ids: type: array items: type: string tag_ids: type: array items: type: string tag_operator: type: string enum: - and - or previous_start_date: description: >- 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]. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ previous_end_date: description: >- End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ merchant_ids: description: >- Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ product_ids: description: >- Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ order_by: default: mention_count type: string enum: - mention_count - win_rate - avg_rating - avg_position direction: default: desc type: string enum: - asc - desc limit: default: 50 type: integer minimum: 1 maximum: 200 offset: default: 0 type: integer minimum: 0 maximum: 9007199254740991 multipart/form-data: schema: type: object properties: project_id: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string start_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ end_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ category_ids: description: >- Filter by shopping categories. Parent categories include descendants. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ country_codes: type: array items: type: string model_channel_ids: type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - google-4 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 - mistral-0 - mistral-1 topic_ids: type: array items: type: string tag_ids: type: array items: type: string tag_operator: type: string enum: - and - or previous_start_date: description: >- 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]. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ previous_end_date: description: >- End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ merchant_ids: description: >- Return only these merchants. Unlike category_ids/product_ids, this does not shrink the share_of_voice denominator. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ product_ids: description: >- Narrow the population to these products — per-product seller breakdowns. share_of_voice is then the share among that product's sellers. type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ order_by: default: mention_count type: string enum: - mention_count - win_rate - avg_rating - avg_position direction: default: desc type: string enum: - asc - desc limit: default: 50 type: integer minimum: 1 maximum: 200 offset: default: 0 type: integer minimum: 0 maximum: 9007199254740991 responses: '200': description: >- 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. content: application/json: schema: type: object properties: data: type: array items: type: object properties: merchant_id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string domain: type: string mention_count: type: number mention_count_delta: type: number share_of_voice: type: number share_of_voice_delta: nullable: true type: number win_rate: type: number win_rate_delta: nullable: true type: number avg_position: nullable: true type: number avg_position_delta: nullable: true type: number avg_rating: nullable: true type: number avg_rating_delta: nullable: true type: number required: - merchant_id - name - domain - mention_count - mention_count_delta - share_of_voice - share_of_voice_delta - win_rate - win_rate_delta - avg_position - avg_position_delta - avg_rating - avg_rating_delta total_count: type: number required: - data - total_count description: >- 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. security: - APIKeyHeader: [] - APIKeyQuery: [] - BearerAuth: [] components: securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key APIKeyQuery: type: apiKey in: query name: api_key BearerAuth: type: http scheme: bearer bearerFormat: JWT ````