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

# List products

`POST /products/list`

Product performance metrics aggregated over a date range. Defaults to the last 7 days if no dates are specified. Data is typically 2-3 days behind the current date. Each product also carries its TikTok Seller Center per-product metrics as sc_* fields: all-channel GMV with its per-channel breakdown (affiliate, seller video, seller live, product card, shop tab), plus orders, units sold, customers, impressions, clicks, CTR, conversion, AOV, GMV per 1,000 impressions, add-to-cart, and refunds. The sc_* fields are null for products not yet on the Seller Center sync.

## Request body

- ProductsListRequest — POST /products/list request body.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'gmv' | 'units_sold' | 'video_count' | 'sample_count' | 'est_commission', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `product_name` string, nullable

## Response `200`

Successful Response

- ProductsListPaginatedResponse
  - `data` ProductListItem[], required
    - `product_id` string, required
    - `product_name` string, nullable
    - `gmv` number, nullable — SUM of product_info.gmv_amount, normalized to float
    - `units_sold` integer, nullable — SUM of item_sold_cnt
    - `refund_units` integer, nullable — SUM of refund_item_cnt
    - `video_count` integer, nullable — SUM of video_cnt
    - `sample_count` integer, nullable — SUM of sample_cnt
    - `live_count` integer, nullable — SUM of live_cnt
    - `est_commission` number, nullable — SUM of est_commission_amount, normalized
    - `product_status` string, nullable — From product_catalog. NULL for unofficial shops.
    - `sc_total_gmv` number, nullable — Total product GMV across all sales channels, from TikTok Seller Center.
    - `sc_orders` number, nullable — Number of orders for this product, from TikTok Seller Center.
    - `sc_units_sold` number, nullable — Units sold for this product, from TikTok Seller Center.
    - `sc_customers` number, nullable — Distinct buyers for this product, from TikTok Seller Center.
    - `sc_aov` number, nullable — Average order value (total GMV / total orders over the date range); null if no orders.
    - `sc_impressions` number, nullable — Product impressions, from TikTok Seller Center.
    - `sc_clicks` number, nullable — Product clicks, from TikTok Seller Center.
    - `sc_ctr` number, nullable — Click-through rate as a percent (total clicks / total impressions over the date range); null if no impressions.
    - `sc_conversion` number, nullable — Conversion rate as a percent (total orders / total clicks over the date range); null if no clicks.
    - `sc_gmv_per_1k_impr` number, nullable — GMV per 1,000 impressions (total GMV / total impressions x 1,000 over the date range); null if no impressions.
    - `sc_add_to_cart` number, nullable — Add-to-cart count for this product, from TikTok Seller Center.
    - `sc_affiliate_gmv` number, nullable — GMV from the affiliate channel.
    - `sc_seller_video_gmv` number, nullable — GMV from the seller's own videos.
    - `sc_seller_live_gmv` number, nullable — GMV from the seller's own live streams.
    - `sc_product_card_gmv` number, nullable — GMV from product cards.
    - `sc_shop_tab_gmv` number, nullable — GMV from the shop tab.
    - `sc_refunds` number, nullable — Refund amount for this product, from TikTok Seller Center.
  - `currency` string, required
  - `pagination` unknown, required
  - `date_range` DateRange
    - `start_date` string, nullable
    - `end_date` string, nullable
  - `shops_queried` string[], nullable — Shop names included when querying multiple shops (x-shop-id: all or comma-separated).

## 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-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)