> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the TikTok GMV Max data source in Adriel.

## 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-sources/o-z/tiktok-gmv-max/how-to-connect).

## 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

<Note>
  **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.
</Note>

### GMV & orders (all levels)

<Note>
  Currency values are reported in the ad account's configured TikTok currency.
</Note>

| 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

<Note>
  **Level-scoped.** Available breakdowns depend on the collection level of the data source.
</Note>

### 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.

## API references (TikTok)

* [TikTok Business API — GMV Max reports](https://business-api.tiktok.com/portal/docs?id=1770171270793729)
* [TikTok Business API — GMV Max store list](https://business-api.tiktok.com/portal/docs?id=1770171271088642)
* [TikTok Business API — OAuth](https://business-api.tiktok.com/portal/docs?id=1738373164380162)

## See also

* [How to connect TikTok GMV Max to Adriel](/data-sources/o-z/tiktok-gmv-max/how-to-connect) (paired how-to)
* [TikTok Ads data reference](/data-sources/o-z/tiktok/data-reference) — general TikTok ad performance
* [TikTok Organic data reference](/data-sources/o-z/tiktok-organic/data-reference) — organic account metrics
* [Shopify data reference](/data-sources/o-z/shopify/data-reference) — direct-to-consumer commerce alongside GMV Max