---
title: "Live GMV Max report (from TikTok)"
method: POST
path: "/gmv-max/report"
tags: ["GMV Max"]
---

# Live GMV Max report (from TikTok)

`POST /gmv-max/report`

## Request

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

Runs TikTok's GMV Max report for this shop on the request — the same data and grains as TikTok's `gmv_max/report/get`, typically under an hour old, where the other GMV Max metric tools read Reacher's sync and can be hours behind.

Choose `dimensions` (campaign_id, item_group_id = product SPU, item_id = post, room_id = LIVE room, duration, stat_time_day or stat_time_hour) and `metrics` (cost, net_cost, orders, cost_per_order, gross_revenue, roi, roas_bid = target ROI, product/creative/LIVE metrics). Product-, post- and LIVE-level rows need `filtering.campaign_ids`. Dates are in the ad account's time zone: up to 1 day with stat_time_hour, 30 days with stat_time_day, 365 days otherwise.

Rows pass TikTok's `dimensions`/`metrics` objects through unchanged (numbers arrive as strings). An identical request within 5 minutes is served from cache (`cached: true`). Each shop may make 120 uncached reports per hour. Single shop only.

## Request body

- GmvMaxReportRequest: ``POST /public/v1/gmv-max/report`` — a live GMV Max report from TikTok.
  - `start_date` string, date, required: Inclusive start date (YYYY-MM-DD) in the ad account's time zone.
  - `end_date` string, date, required: Inclusive end date (YYYY-MM-DD) in the ad account's time zone. Up to 1 day with stat_time_hour, 30 days with stat_time_day, 365 days with no time dimension.
  - `dimensions` string[], required: Grouping. advertiser_id and campaign_id stand alone; item_group_id, item_id, room_id and duration need filtering.campaign_ids; item_id also needs filtering.item_group_ids; duration needs filtering.room_ids or filtering.item_group_ids. stat_time_day / stat_time_hour split time and cannot be used alone.
  - `metrics` string[], required: Metrics and attributes. Money metrics: cost, net_cost, orders, cost_per_order, gross_revenue, roi. Campaign attributes include roas_bid (the target ROI). roi is 0.00 when cost is 0 — that is a placeholder, not a ratio.
  - `filtering` GmvMaxReportFilter: TikTok's ``filtering`` object for ``gmv_max/report/get``.
    - `campaign_ids` string[], nullable: GMV Max campaign IDs. Required for the item_group_id, item_id, room_id and duration dimensions.
    - `item_group_ids` string[], nullable: Product SPU IDs. Required (with campaign_ids) for the item_id dimension.
    - `room_ids` string[], nullable: LIVE room IDs. Anchors the duration dimension for LIVE campaigns.
    - `campaign_statuses` string[], nullable: Campaign statuses to include. TikTok's default excludes deleted campaigns.
    - `gmv_max_promotion_types` string[], nullable: Product GMV Max, LIVE GMV Max, or both.
    - `creative_delivery_statuses` string[], nullable: Creative delivery statuses (creative-level reports). TikTok spells one value `NOT_DELIVERYING`.
    - `campaign_name` string, nullable: Fuzzy match on campaign name.
    - `search_word` string, nullable: Fuzzy match on video title, TikTok post ID or account name.
  - `sort_field` string, nullable: A metric to sort by, e.g. `cost`.
  - `sort_type` 'ASC' | 'DESC', nullable
  - `enable_total_metrics` boolean: Also return totals across every page in `total_metrics`.
  - `page` integer
  - `page_size` integer

## Response `200`

Successful Response

- GmvMaxReportResponse: POST /gmv-max/report — live from TikTok's ``gmv_max/report/get``.
  - `shop_id` integer, required
  - `advertiser_id` string, required
  - `store_id` string, required
  - `currency` string, required: ISO currency code for the shop's region.
  - `source` 'live': Always `live`: fetched from TikTok, not from Reacher's sync.
  - `fetched_at` string, nullable, required: When TikTok returned this data. Repeating the same request within 5 minutes returns this same result (see `cached`).
  - `cached` boolean, required: True when served from the 5-minute cache rather than a new TikTok call.
  - `data` GmvMaxReportRow[], required: The report rows for this page.
    - `dimensions` object, required: The requested dimensions for this row, e.g. `{campaign_id, stat_time_hour}`.
    - `metrics` object, required: The requested metrics. TikTok returns numbers as strings (e.g. `"123.30"`); they are passed through unchanged.
  - `total_metrics` object, nullable: Totals across every page; present when `enable_total_metrics` was set.
  - `page_info` GmvMaxReportPageInfo
    - `page` integer, required
    - `page_size` integer, required
    - `total_number` integer, required
    - `total_page` integer, required

## Other responses

- `400`: Invalid request / shop not connected to GMV Max.
- `422`: TikTok rejected the report request.
- `429`: Hourly live-report cap reached, or TikTok is throttling.
- `502`: TikTok failed transiently; safe to retry.

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-16** `8c30101a864b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/gmv-max/report/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)