---
title: "Products or videos ranked by new-customer acquisition"
method: GET
path: "/seller-center/buyers-ranking"
tags: ["Seller Center"]
---

# Products or videos ranked by new-customer acquisition

`GET /seller-center/buyers-ranking`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/seller-center/buyers-ranking`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

The shop's products (`ranking_type=product`) or videos (`ranking_type=video`) ranked by how many **new customers** they brought in, from `customers.sc_buyers_ranking`. Use it to find the product or piece of content that actually acquires buyers, as opposed to the one that generates the most GMV from buyers you already had.

`customer_contribution` is the entity's share (0-1) of the shop's new customers over TikTok's trailing `period_months` window (12 by default).

No date window: this is a snapshot ranking that TikTok recomputes and the collector overwrites wholesale. Collection of this ranking is currently paused upstream, so the response reflects the last snapshot collected for the shop. Single-shop only — set `x-shop-id` to a specific shop ID. An empty result is a normal 200 response: Seller Center collection is per-shop and still rolling out.

## Query parameters

- `ranking_type` 'product' | 'video': Rank products or videos.
- `limit` integer: Max entries (max 200).

## Response `200`

Successful Response

- BuyersRankingResponse
  - `shop_id` integer, required
  - `data` BuyersRankingEntry[], required
    - `rank` integer, required
    - `ranking_type` string, required: `product` or `video`.
    - `entity_id` string, required: Product id or video id, per `ranking_type`.
    - `entity_name` string, nullable
    - `creator_name` string, nullable: Public TikTok handle, on video rankings.
    - `new_customers` integer, required: Buyers whose first purchase from this shop came through this entity.
    - `customer_contribution` number, nullable: This entity's share of the shop's new customers (0-1).
    - `period_months` integer, nullable: Trailing window TikTok ranked over (typically 12 months).
    - `customer_type` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)