> ## 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 Shopee Ads data source in Adriel.
## Introduction
Shopee Ads is the marketplace advertising platform for Shopee, the Southeast Asian e-commerce marketplace. It covers product-level campaigns that promote a shop's listings across Shopee's search and discovery surfaces, reporting spend against marketplace outcomes such as GMV and orders. The connector pulls product-level campaign performance and campaign metadata from the Shopee Open Platform API (v2).
As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.
This data source is distinct from the Shopee e-commerce connector: Shopee Ads reports on paid campaign performance, while the Shopee connector reports on shop orders and products.
To connect this data source, see [How to connect Shopee Ads to Adriel](/data-sources/o-z/shopee-ads/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers product-level campaigns and their metadata (name, status, bidding method, placement, budget, and schedule). It refreshes twice daily, at **6:30 AM UTC** and **1:30 PM UTC**, and is upserted so campaign changes (budget, status) are reflected without a full rebuild.
### Reports data
Reports include daily performance for each product-level campaign — impressions, clicks, spend, GMV, and orders.
**Daily cache.** Report data is served from a daily cache rather than fetched live on each dashboard load. Dashboard data is composed from the most recent cached snapshot.
**Initial fill.** On data source creation, the cache fills with **180 days** of historical daily data.
**Refresh schedule.** Reports refresh once daily at **2:00 AM UTC**, syncing a rolling **last 10 days** of data.
Data is considered reliable within the cache sync window. Because delivery is cache-based, activity from the most recent hours may not appear until the next daily refresh.
## Architecture levels
Campaign (product-level)
Shopee Ads exposes a single reporting level: the product-level campaign within a connected shop. There is no ad account, ad set, or ad hierarchy.
## Date range limits
Historical data is capped at approximately **180 days** (about six months). This is a practical ceiling of the Shopee Ads API — queries beyond roughly six months fail — rather than a configurable Adriel setting. The initial backfill is limited to 180 days for the same reason.
## 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 `clicks` is the literal field name delivered by the connector. *Italic text* describes how a value is produced when it doesn't map cleanly to a single field (these are Adriel-computed).
Shopee Ads reports both **broad** and **direct** attribution for conversion outcomes. Direct metrics credit outcomes on the advertised item itself; broad metrics credit outcomes on any item in the shop attributed to the ad.
### Delivery & clicks
| Metric | Description | Data type | API Key |
| ----------- | ------------------------- | ---------- | --------------------------------------- |
| Impressions | Times the ads were shown. | Number | `impression` |
| Clicks | Ad clicks. | Number | `clicks` |
| CTR | Click-through rate. | Percentage | *Adriel-computed (clicks / impression)* |
### Cost & spend
| Metric | Description | Data type | API Key |
| -------------------------- | ------------------------------------------------------ | ---------- | ------------------------------------------- |
| Ad spend | Total amount spent on the campaign. | Currency | `expense` |
| Cost per conversion | Spend divided by broad-attributed orders. | Currency | *Adriel-computed (expense / broad\_order)* |
| Cost per direct conversion | Spend divided by direct-attributed orders. | Currency | *Adriel-computed (expense / direct\_order)* |
| Broad CIR | Cost-to-income ratio — spend as a share of broad GMV. | Percentage | *Adriel-computed (expense / broad\_gmv)* |
| Direct CIR | Cost-to-income ratio — spend as a share of direct GMV. | Percentage | *Adriel-computed (expense / direct\_gmv)* |
### Conversions & value
| Metric | Description | Data type | API Key |
| ---------------------- | ------------------------------------------------------------------ | ---------- | ------------------------------------------ |
| Broad GMV | Gross merchandise value attributed to the ad across any shop item. | Currency | `broad_gmv` |
| Direct GMV | Gross merchandise value attributed to the advertised item. | Currency | `direct_gmv` |
| Broad orders | Orders attributed to the ad across any shop item. | Number | `broad_order` |
| Direct orders | Orders attributed to the advertised item. | Number | `direct_order` |
| Broad items sold | Items sold across broad-attributed orders. | Number | `broad_order_amount` |
| Direct items sold | Items sold in direct-attributed orders. | Number | `direct_order_amount` |
| Conversion rate | Broad-attributed orders divided by clicks. | Percentage | *Adriel-computed (broad\_order / clicks)* |
| Direct conversion rate | Direct-attributed orders divided by clicks. | Percentage | *Adriel-computed (direct\_order / clicks)* |
| Broad ROI | Return on investment — broad GMV divided by spend. | Ratio | *Adriel-computed (broad\_gmv / expense)* |
| Direct ROI | Return on investment — direct GMV divided by spend. | Ratio | *Adriel-computed (direct\_gmv / expense)* |
### Campaign metadata
| Metric | Description | Data type | API Key |
| ------------------- | ------------------------------------------------------------- | --------- | ------------------------------ |
| Campaign name | Name of the product-level campaign. | Text | `campaign_ad_name` |
| Campaign budget | Configured campaign budget. | Currency | `campaign_campaign_budget` |
| Campaign status | Current campaign status. | Text | `campaign_campaign_status` |
| Ad type | Product-ad type of the campaign. | Text | `campaign_ad_type` |
| Bidding method | Bidding method configured on the campaign. | Text | `campaign_bidding_method` |
| Placement | Campaign placement setting. | Text | `campaign_campaign_placement` |
| Starts | Campaign start date. | Date | `campaign_campaign_start_time` |
| Ends | Campaign end date. | Date | `campaign_campaign_end_time` |
| Advertised item IDs | Item IDs promoted by the campaign, as a comma-separated list. | Text | `campaign_item_id_list` |
## Breakdowns
### Campaign structure
| Breakdown | Description | API Key |
| -------------- | -------------------------------- | ----------------------------- |
| Campaign | Group by product-level campaign. | `campaign_id` |
| Campaign name | Group by campaign name. | `campaign_ad_name` |
| Status | Group by campaign status. | `campaign_campaign_status` |
| Ad type | Group by product-ad type. | `campaign_ad_type` |
| Bidding method | Group by bidding method. | `campaign_bidding_method` |
| Placement | Group by campaign placement. | `campaign_campaign_placement` |
### Time & date grouping
Shopee returns daily records; Adriel groups them into these views for reporting.
| 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 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
These grouping options are provided by Adriel for cross-source rollup rather than returned by Shopee.
| Breakdown | Description |
| ----------- | -------------------------------------------------------- |
| Channel | Constant grouping label used for cross-connector rollup. |
| No Grouping | Do not break down; return one aggregated row. |
## Limitations
* **180-day historical ceiling** — data older than roughly six months is not available; the Shopee Ads API rejects queries beyond that window.
* **Daily cache delivery** — report data is served from a once-daily cache (2:00 AM UTC, last 10 days), so the most recent hours of activity may not appear until the next refresh.
* **Single reporting level** — only product-level campaigns are exposed; there is no ad account, ad set, or ad hierarchy.
* **Ratio metrics are computed, not stored** — CTR, conversion rates, CIR, and ROI are derived from raw metrics at query time; a raw `cpc` field exists in the source type but is neither stored nor exposed.
* **Campaign start/end dates may not render** — campaign schedule timestamps can display incorrectly because of a stored-format mismatch in the connector; treat Starts/Ends as unreliable until fixed.
* **Fetch is all-or-nothing per refresh** — if any campaign chunk returns an API error during a report fetch, the entire refresh fails and no partial data is written.
## API references
* [Shopee Open Platform API documentation](https://open.shopee.com/documents) — official Shopee Open Platform (v2) reference, including the product-level ads endpoints.
## See also
* [How to connect Shopee Ads to Adriel](/data-sources/o-z/shopee-ads/how-to-connect) (paired how-to)
* [Shopee data reference](/data-sources/o-z/shopee/data-reference) — for the Shopee e-commerce (orders and products) connector