Data reference - Adriel Knowledge Base

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 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 — official Shopee Open Platform (v2) reference, including the product-level ads endpoints.

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Delivery & clicks

​Cost & spend

​Conversions & value

​Campaign metadata

​Breakdowns

​Campaign structure

​Time & date grouping

​Overview

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Delivery & clicks

Cost & spend

Conversions & value

Campaign metadata

Breakdowns

Campaign structure

Time & date grouping

Overview

Limitations

API references

See also