---
title: "Daily product-level GMV Max metrics (per product, per campaign)"
method: POST
path: "/gmv-max/products/timeseries"
tags: ["GMV Max"]
---

# Daily product-level GMV Max metrics (per product, per campaign)

`POST /gmv-max/products/timeseries`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/gmv-max/products/timeseries`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

Daily GMV Max metrics broken down to the **product** (SPU / item_group_id) level for one shop — cost, gross revenue (GMV), SKU orders, ROI, and cost-per-order per product per day. This is the grain behind TikTok Seller Center's per-campaign *Product* table.

Optionally filter to a single `campaign_id` and/or `item_group_id`. `item_group_id` (aliased as `product_id`) is the join key to the product / Seller Center product datasets.

Single-shop only — set `x-shop-id` to a specific shop ID. Defaults to the last 30 days ending yesterday; max range 90 days. Empty `data` is a normal 200 (a shop may have no GMV Max campaigns).

`roi` and `cost_per_order` are TikTok's stored daily values — for window totals use `/gmv-max/products/summary`, which recomputes them from the summed bases.

## Request body

- GmvMaxProductTimeseriesRequest: POST /gmv-max/products/timeseries — daily per-product GMV Max metrics for one shop (product = TikTok SPU / item_group_id).
  - `start_date` string, date, nullable: Inclusive window start (YYYY-MM-DD). Defaults to 29 days before ``end_date`` (30-day window).
  - `end_date` string, date, nullable: Inclusive window end (YYYY-MM-DD). Defaults to yesterday (today's row is still incomplete).
  - `campaign_id` string, nullable: Restrict to a single GMV Max campaign.
  - `item_group_id` string, nullable: Restrict to a single product (TikTok SPU / item_group_id).

## Response `200`

Successful Response

- GmvMaxProductTimeseriesResponse
  - `shop_id` integer, required
  - `currency` string, required: ISO currency code for the shop's region.
  - `start_date` string, required
  - `end_date` string, required
  - `data` GmvMaxProductMetricItem[], required
    - `date` string, required: ISO 8601 date (YYYY-MM-DD) for this metric row.
    - `campaign_id` string, required: Owning GMV Max campaign id.
    - `item_group_id` string, required: TikTok SPU id (the product).
    - `product_id` string, required: Alias of item_group_id — join key to product/sales datasets.
    - `spend` number, nullable: Ad spend for this product on this campaign/day.
    - `cost` number, nullable: Deprecated alias of `spend`; use `spend`.
    - `gross_revenue` number, nullable: GMV attributed to this product/day.
    - `orders` integer, nullable: SKU orders for this product/day.
    - `roi` number, nullable: TikTok ROI (~ROAS) for this product/day (daily value).
    - `ad_roi` number, nullable: Ad ROI = gross_revenue (GMV) / cost (GMV Max spend) for this product/day, computed directly from this row and rounded to 4dp. Null when cost is 0 or missing. Explicitly named for discoverability (CORE-6538). Unlike `roi` — which is TikTok's stored daily value under TikTok's own attribution — this is the transparent GMV/spend ratio and may differ from `roi`.
    - `cost_per_order` number, nullable: TikTok-native daily cost per order (not a window rollup).

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 3 info
  - api operation id `gmv_max_products_timeseries_gmv_max_products_timeseries_post` removed and replaced with `gmv_max_products_timeseries`
  - added the optional property `data/items/spend` to the response with the `200` status
  - response property `data/items/cost` deprecated

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/gmv-max/products/timeseries/post.md)

---

[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)