Data reference

Introduction

TikTok GMV Max is TikTok Shop’s automated advertising product for driving gross merchandise value (GMV) — TikTok’s ad system optimizes spend against shop revenue across live shopping, short-form product ads, and shoppable creatives. This connector reads GMV Max campaign performance from TikTok’s Business API (v1.3), organized across four hierarchical collection levels: Campaign, Product, Creative, and Livestream. As a marketing connector with e-commerce KPIs, metrics and breakdowns are standardized so widgets can aggregate alongside ad-platform and commerce sources without additional configuration. To connect this data source, see How to connect TikTok GMV Max to Adriel.

Data refresh strategy

Architecture data

Architecture covers TikTok ad accounts and the TikTok Shop stores linked to each account. The store list is refreshed on every sync when “Use all stores” is enabled; when “Select stores” is used, the fixed list chosen at connection time is used.

Reports data

Daily cache. Report data is fetched from TikTok’s GMV Max API on a daily schedule; dashboards read from the cached snapshot rather than triggering live requests. Refresh schedule. The cache refreshes daily at 10:00 PM UTC on a rolling 3-day window. Initial back-fill. After connection, the last 90 days of historic data is retrieved.

Architecture levels

Ad account → Store → Campaign, plus per-Campaign sub-levels for Product, Creative, and Livestream.

Collection levels

GMV Max data is organized across four hierarchical collection levels. Each level exposes a different set of metrics and breakdowns.

Level	What it covers	Depends on
Campaign	Campaign-level spend, GMV, orders, live-viewership metrics, and campaign schedule / bid settings.	—
Product	Per-product spend, GMV, and orders inside a campaign — plus product name, image, and status.	Campaign synced
Creative	Per-creative spend, GMV, orders, impressions, clicks, and video-view thresholds.	Product synced
Livestream	Per-livestream spend, GMV, orders, live-viewership, and stream metadata.	Campaign synced; incompatible with Product / Creative

Date range limits

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly / Quarterly / Yearly	No explicit cap (bounded by the 90-day initial back-fill window)

Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like gross_revenue is the literal TikTok Business API field. Metrics are grouped by which collection level they apply to. Italic text describes how a value is produced when it doesn’t map cleanly to a single API field — typically Adriel-side derivation from a rate metric.

GMV & orders (all levels)

Currency values are reported in the ad account’s configured TikTok currency.

Metric	Description	Data type	API Key
Ad spend	Total amount spent on the campaign / product / creative / livestream.	Currency	`cost`
Net ad spend	Spend net of TikTok-side adjustments (Campaign, Livestream only).	Currency	`net_cost`
GMV	Gross merchandise value attributed to the ads.	Currency	`gross_revenue`
Orders	Attributed order count.	Number	`orders`
ROAS	Return on ad spend — GMV divided by spend.	Ratio	Adriel-computed

Campaign settings (Campaign level)

Metric	Description	Data type	API Key
Campaign status	Current operational status of the campaign.	Text	`operation_status`
Bid type	Bid strategy on the campaign.	Text	`bid_type`
Target ROAS bid	Target ROAS bid on the campaign.	Ratio	`roas_bid`
Max delivery budget	Configured max delivery budget.	Currency	`max_delivery_budget`
Target ROI budget	Configured target ROI budget.	Currency	`target_roi_budget`
Schedule type	Campaign schedule type.	Text	`schedule_type`
Schedule start	Campaign start time.	Date	`schedule_start_time`
Schedule end	Campaign end time.	Date	`schedule_end_time`

Live viewership (Campaign and Livestream levels)

Metric	Description	Data type	API Key
Live views	Total live-stream views.	Number	`live_views`
10-second live views	Live-stream views of at least 10 seconds.	Number	`10_second_live_views`
Live follows	New follows attributed to the live stream.	Number	`live_follows`

Product metadata (Product level)

Metric	Description	Data type	API Key
Product name	Product name.	Text	`product_name`
Product image	Primary product image URL.	URL	`product_image_url`
Product status	Product status on TikTok Shop.	Text	`product_status`

Creative delivery (Creative level)

Metric	Description	Data type	API Key
Product impressions	Impressions on product-tagged creatives.	Number	`product_impressions`
Product clicks	Clicks on product-tagged creatives.	Number	`product_clicks`
Ad clicks	Derived click count.	Number	Adriel-derived from `ad_click_rate × product_impressions`
Ad conversions	Derived conversion count.	Number	Adriel-derived from `ad_conversion_rate × product_clicks`
Creative name / title	Creative title.	Text	`title` / `creative_name`
Creative delivery status	Delivery status of the creative.	Text	`creative_delivery_status`

Creative video performance (Creative level)

Metric	Description	Data type	API Key
Video views (2s)	Views of at least 2 seconds.	Number	Adriel-derived from rate × impressions
Video views (6s)	Views of at least 6 seconds.	Number	Adriel-derived from rate × impressions
Video played to 25% / 50% / 75% / 100%	Views reaching each completion threshold.	Number	Adriel-derived from rate × impressions

Livestream metadata (Livestream level)

Metric	Description	Data type	API Key
Live name	Livestream name.	Text	`live_name`
Live status	Livestream status.	Text	`live_status`
Live launched at	Livestream start timestamp.	Date	`live_launched_time`
Live duration	Livestream duration.	Duration	`live_duration`

Breakdowns

Level-scoped. Available breakdowns depend on the collection level of the data source.

Standard hierarchy

Breakdown	Description	API Key
Ad account	Group by ad account.	`advertiser_id`
Store	Group by TikTok Shop store.	`store_id`
Campaign	Group by campaign (all levels).	`campaign_id`
Product	Group by product (Product / Creative levels).	`item_group_id`
Creative	Group by creative (Creative level).	`item_id`
Livestream	Group by livestream room (Livestream level).	`room_id`

Time & date grouping

Breakdown	Description
Auto Time Breakdown	Automatically picks the best granularity for the date range.
Daily	Split reports by day.
Weekly (Start: Mon)	Split reports by ISO week, starting Monday.
Weekly (Start: Sun)	Split reports by week, starting Sunday.
Monthly	Split reports by calendar month.
Quarterly	Split reports by calendar quarter.
Yearly	Split reports by calendar year.

Overview & status

Breakdown	Description
Channel	Constant grouping label — for TikTok GMV Max this is always “tiktok”. Used for cross-connector rollup.
No Grouping	Do not break down; return one aggregated row.
Datasource Name	Group by Adriel datasource name.

Limitations

90-day initial back-fill. Data older than 90 days from the connection date cannot be retrieved.
Collection level is fixed per data source. To compare across levels (Campaign, Product, Creative, Livestream) create separate data sources, one per level.
Livestream is a separate branch. Livestream metrics cannot be broken down by product or creative in the same data source.
Creative clicks and video-view counts are derived from TikTok’s rate metrics multiplied by impressions or clicks, then rounded. They may not exactly match the counts shown in TikTok’s UI.
One store ID per API request. For multi-store ad accounts, each store issues its own API call per date per level, so wide date ranges consume more of TikTok’s API quota.
Auto-reconnect disabled. If the TikTok token expires the connection is not automatically re-established; the user must reconnect manually.
Distinct from TikTok Ads. Metrics may not reconcile against a TikTok Ads data source because the two use different TikTok reporting products.

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Collection levels

Date range limits

Metrics

GMV & orders (all levels)

Campaign settings (Campaign level)

Live viewership (Campaign and Livestream levels)

Product metadata (Product level)

Creative delivery (Creative level)

Creative video performance (Creative level)

Livestream metadata (Livestream level)

Breakdowns

Standard hierarchy

Time & date grouping

Overview & status

Limitations

API references (TikTok)

See also

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Collection levels

​Date range limits

​Metrics

​GMV & orders (all levels)

​Campaign settings (Campaign level)

​Live viewership (Campaign and Livestream levels)

​Product metadata (Product level)

​Creative delivery (Creative level)

​Creative video performance (Creative level)

​Livestream metadata (Livestream level)

​Breakdowns

​Standard hierarchy

​Time & date grouping

​Overview & status

​Limitations

​API references (TikTok)

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Collection levels

Date range limits

Metrics

GMV & orders (all levels)

Campaign settings (Campaign level)

Live viewership (Campaign and Livestream levels)

Product metadata (Product level)

Creative delivery (Creative level)

Creative video performance (Creative level)

Livestream metadata (Livestream level)

Breakdowns

Standard hierarchy

Time & date grouping

Overview & status

Limitations

API references (TikTok)

See also