TOOL API
gmv_
Runs a report for GMV Max Campaigns (Product or LIVE). By default, the response only includes undeleted campaigns. Returns e-commerce outcomes only. GMV Max campaigns do NOT appear in /report/integrated/get — use this endpoint only. Non-delivering campaigns return all-zero rows: zero means "did not deliver", not "performed poorly". Access depends on the GMV Max Campaign type and the metric level you want to query; ensure you meet the prerequisites and permissions for Product GMV Max Campaigns or LIVE GMV Max Campaigns. Use /gmv_max/store/list/ to get TikTok Shop IDs that are available for GMV Max Campaigns.
Call information
- Tool slug
- tiktok-ads.gmv_max_report_get
- Provider
- TikTok for Business
- Average response
- 0 ms
- Calls in 7 days
- 0
Input parameters
advertiser_idrequiredAdvertiser ID.
dimensionsrequiredHierarchy — lower levels need anchoring filters, else 40002: - advertiser_id, campaign_id — usable alone - item_group_id, room_id — need filtering.campaign_ids - item_id — needs filtering.campaign_ids AND filtering.item_group_ids - duration — needs filtering.room_ids (LIVE) or filtering.item_group_ids (Product) - stat_time_day, stat_time_hour — time splits, never alone Dimension groupings for the report. Supported values: `advertiser_id` (group by advertiser ID), `campaign_id` (group by campaign ID), `stat_time_day` (group by day; time-split dimension, cannot be used alone), `stat_time_hour` (group by hour; time-split dimension, cannot be used alone), `item_group_id` (group by SPU ID), `item_id` (group by post ID), `room_id` (group by room ID), and `duration` (group by duration). Example: `["campaign_id", "stat_time_day"]` groups by campaign and day. Available dimensions vary by the metric type you query.
enable_total_metricsWhether to return total added-up values for the requested metrics across all pages. When `true`, the response includes aggregate metric data for all pages as you query different pages. Supported values: `true`, `false`. Default value: `false`.
end_daterequiredQuery end date, inclusive, in `YYYY-MM-DD` format and based on the ad account time zone. Example: `2025-02-01`. The allowed date range depends on `dimensions`: if `dimensions` does not include `stat_time_day` or `stat_time_hour`, the range can be up to 365 days; if `dimensions` includes `stat_time_day`, the range can be up to 30 days; if `dimensions` includes `stat_time_hour`, the range can be up to one day.
filteringFiltering conditions. Required filters depend on dimensions. If dimensions contains [item_group_id, item_id, duration]: campaign_ids is REQUIRED.If dimensions contains [item_id]: item_group_ids also REQUIRED.
metricsrequiredMetrics to query. E-commerce outcomes only; no traffic metrics. Valid: gross_revenue, cost, net_cost, roi, orders, cost_per_order Use `cost`, not `spend` (`spend` works in /report/integrated/get, not here). `roi` returns 0.00 when cost is 0 — placeholder, not a real ratio.
pageCurrent page number. Value range: >= 1. Default value: 1.
page_sizePage size. Value range: 1-1,000. Default value: 10.
sort_fieldSorting field. Not sorted by default. We recommend setting this field so results are returned in a logical order. Supported sort fields differ for Product GMV Max Campaigns and LIVE GMV Max Campaigns.
sort_typeSorting order. Default value: `DESC`.
start_daterequiredQuery start date, inclusive, in `YYYY-MM-DD` format and based on the ad account time zone. Example: `2025-01-01`.
store_idsrequiredList of TikTok Shop IDs to query. Max size: 1. Obtain valid shop IDs from /gmv_max/store/list/ and use only shops where `is_gmv_max_available` is `true`.