> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Shopee Ads as a data source
> Bring advertising data from Shopee Ads to Nekt.
Shopee Ads is Shopee's in-platform advertising system that allows sellers to promote products through search and discovery placements. The Shopee Ads API provides access to campaign configurations, bidding strategies, and daily performance metrics for product-level ad campaigns.
## Configuring Shopee Ads as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Shopee Ads option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need to authorize Nekt to access your Shopee seller data. Click on the **Shopee Authorization** button and log in with your Shopee seller account. Grant the necessary permissions for the shop you want to extract data from.
The following configurations are available:
* **API URL**: Select the appropriate API endpoint for your region:
* `https://partner.shopeemobile.com` - Global (Southeast Asia)
* `https://openplatform.shopee.com.br` - Brazil
* `https://openplatform.shopee.cn` - China
* **Start Date**: The earliest date from which ad performance records will be synced. If not provided, all available historical data will be extracted.
Make sure you have the correct API permissions enabled in your Shopee Partner account. The connector requires access to the Ads API to retrieve campaign and performance data.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data, which is good if you want to keep historical performance trends.
* Full table: every time the extraction happens, we'll get the current state of the data, which is good for campaign configuration snapshots.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Shopee Ads and their corresponding fields:
List of all product-level ad campaign IDs in your shop. This is a parent stream used to fetch campaign details and performance data.
| Field | Type | Description |
| :------------ | :------ | :------------------------------- |
| `campaign_id` | Integer | Unique campaign identifier |
| `ad_type` | String | Type of campaign: auto or manual |
Detailed campaign configuration including bidding strategy, budget, placement, and keyword settings.
| Field | Type | Description |
| :-------------------------------------------- | :------ | :--------------------------------------------------------- |
| `campaign_id` | Integer | Unique campaign identifier |
| `common_info` | Object | Common campaign settings |
| `common_info.ad_type` | String | Campaign type: auto, manual |
| `common_info.ad_name` | String | Campaign name |
| `common_info.campaign_status` | String | Status: ongoing, scheduled, ended, paused, deleted, closed |
| `common_info.bidding_method` | String | Bidding method: auto, manual |
| `common_info.campaign_placement` | String | Ad placement: search, discovery, all |
| `common_info.campaign_budget` | Number | Campaign budget (0 = unlimited) |
| `common_info.campaign_duration` | Object | Start and end time (Unix timestamps) |
| `common_info.item_id_list` | Array | Product IDs under this campaign |
| `manual_bidding_info` | Object | Manual bidding settings |
| `manual_bidding_info.enhanced_cpc` | Boolean | Whether Enhanced CPC is enabled |
| `manual_bidding_info.selected_keywords` | Array | Keywords with match type and bid price |
| `manual_bidding_info.discovery_ads_locations` | Array | Discovery placement locations and bid prices |
| `auto_bidding_info` | Object | Auto bidding settings |
| `auto_bidding_info.roas_target` | Number | Target ROAS for auto bidding |
| `auto_product_ads_info` | Array | Products in auto campaigns with name, status, and item\_id |
Daily performance metrics per campaign, including impressions, clicks, spend, and attribution data with both broad and direct conversion tracking.
| Field | Type | Description |
| :-------------------- | :------ | :----------------------------------------------------- |
| `campaign_id` | Integer | Campaign identifier |
| `ad_type` | String | Campaign type: auto, manual |
| `campaign_placement` | String | Ad placement: search, discovery, all |
| `ad_name` | String | Campaign name |
| `date` | String | Performance date (YYYY-MM-DD, replication key) |
| `impression` | Integer | Number of times the ad was shown |
| `clicks` | Integer | Number of ad clicks |
| `ctr` | Number | Click-through rate (%) |
| `expense` | Number | Amount spent on the ad |
| `broad_gmv` | Number | Revenue from any product within 7 days of ad click |
| `broad_order` | Integer | Orders for any product within 7 days of ad click |
| `broad_order_amount` | Integer | Total quantity purchased within 7 days of ad click |
| `broad_roi` | Number | Broad ROAS (GMV / expense) |
| `broad_cir` | Number | Broad ACOS (expense / GMV x 100%) |
| `cr` | Number | Conversion rate (%) |
| `cpc` | Number | Cost per conversion |
| `direct_order` | Integer | Orders for the advertised product within 7 days |
| `direct_order_amount` | Integer | Quantity of advertised product purchased within 7 days |
| `direct_gmv` | Number | Revenue from the advertised product within 7 days |
| `direct_roi` | Number | Direct ROAS (direct GMV / expense) |
| `direct_cir` | Number | Direct ACOS (expense / direct GMV x 100%) |
| `direct_cr` | Number | Direct conversion rate (%) |
| `cpdc` | Number | Cost per direct conversion |
# Use Cases for Data Analysis
This guide outlines valuable business intelligence use cases when consolidating Shopee Ads data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer).
### 1. Campaign Performance Overview
Analyze campaign-level ad performance to identify top-performing and underperforming campaigns.
**Business Value:**
* Identify which campaigns generate the highest ROAS
* Optimize ad spend allocation across campaigns
* Track advertising efficiency trends over time
```sql theme={null}
SELECT
c.campaign_id,
ci.ad_name,
ci.campaign_status,
ci.ad_type,
ci.campaign_placement,
SUM(p.impression) AS total_impressions,
SUM(p.clicks) AS total_clicks,
ROUND(AVG(p.ctr), 2) AS avg_ctr,
ROUND(SUM(p.expense), 2) AS total_spend,
ROUND(SUM(p.broad_gmv), 2) AS total_revenue,
ROUND(SUM(p.broad_gmv) / NULLIF(SUM(p.expense), 0), 2) AS roas
FROM
nekt_raw.shopee_ads_ads_product_campaigns c
CROSS JOIN UNNEST(ARRAY[c.common_info]) AS t(ci)
LEFT JOIN nekt_raw.shopee_ads_ads_daily_product_campaign_performance p
ON c.campaign_id = p.campaign_id
GROUP BY
c.campaign_id, ci.ad_name, ci.campaign_status, ci.ad_type, ci.campaign_placement
ORDER BY
total_revenue DESC
LIMIT 20
```
```sql theme={null}
SELECT
c.campaign_id,
c.common_info.ad_name,
c.common_info.campaign_status,
c.common_info.ad_type,
c.common_info.campaign_placement,
SUM(p.impression) AS total_impressions,
SUM(p.clicks) AS total_clicks,
ROUND(AVG(p.ctr), 2) AS avg_ctr,
ROUND(SUM(p.expense), 2) AS total_spend,
ROUND(SUM(p.broad_gmv), 2) AS total_revenue,
ROUND(SAFE_DIVIDE(SUM(p.broad_gmv), SUM(p.expense)), 2) AS roas
FROM
`nekt_raw.shopee_ads_ads_product_campaigns` c
LEFT JOIN `nekt_raw.shopee_ads_ads_daily_product_campaign_performance` p
ON c.campaign_id = p.campaign_id
GROUP BY
c.campaign_id, c.common_info.ad_name, c.common_info.campaign_status,
c.common_info.ad_type, c.common_info.campaign_placement
ORDER BY
total_revenue DESC
LIMIT 20
```
| campaign\_id | ad\_name | campaign\_status | ad\_type | total\_impressions | total\_clicks | avg\_ctr | total\_spend | total\_revenue | roas |
| ------------ | ----------------- | ---------------- | -------- | ------------------ | ------------- | -------- | ------------ | -------------- | ---- |
| 100001 | Summer Sale Promo | ongoing | auto | 245,000 | 8,450 | 3.45 | 1,250.00 | 8,750.00 | 7.00 |
| 100002 | Best Sellers Push | ongoing | manual | 189,000 | 6,230 | 3.30 | 980.00 | 5,880.00 | 6.00 |
| 100003 | New Arrivals | paused | auto | 67,000 | 1,890 | 2.82 | 450.00 | 1,575.00 | 3.50 |
### 2. Daily Ad Spend and Revenue Trend
Track daily advertising spend versus revenue to monitor campaign efficiency over time.
**Business Value:**
* Monitor daily ROAS trends
* Detect sudden drops in ad performance
* Plan budget adjustments based on historical patterns
```sql theme={null}
SELECT
date,
SUM(impression) AS total_impressions,
SUM(clicks) AS total_clicks,
ROUND(SUM(expense), 2) AS total_spend,
ROUND(SUM(broad_gmv), 2) AS total_revenue,
ROUND(SUM(broad_gmv) / NULLIF(SUM(expense), 0), 2) AS daily_roas,
SUM(broad_order) AS total_orders
FROM
nekt_raw.shopee_ads_ads_daily_product_campaign_performance
WHERE
date >= DATE_FORMAT(CURRENT_DATE - INTERVAL '30' DAY, '%Y-%m-%d')
GROUP BY
date
ORDER BY
date DESC
```
```sql theme={null}
SELECT
date,
SUM(impression) AS total_impressions,
SUM(clicks) AS total_clicks,
ROUND(SUM(expense), 2) AS total_spend,
ROUND(SUM(broad_gmv), 2) AS total_revenue,
ROUND(SAFE_DIVIDE(SUM(broad_gmv), SUM(expense)), 2) AS daily_roas,
SUM(broad_order) AS total_orders
FROM
`nekt_raw.shopee_ads_ads_daily_product_campaign_performance`
WHERE
date >= FORMAT_DATE('%Y-%m-%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
GROUP BY
date
ORDER BY
date DESC
```
| date | total\_impressions | total\_clicks | total\_spend | total\_revenue | daily\_roas | total\_orders |
| ---------- | ------------------ | ------------- | ------------ | -------------- | ----------- | ------------- |
| 2025-04-19 | 15,230 | 523 | 85.50 | 512.00 | 5.99 | 18 |
| 2025-04-18 | 14,890 | 498 | 79.20 | 475.00 | 6.00 | 15 |
| 2025-04-17 | 16,100 | 567 | 92.30 | 645.00 | 6.99 | 22 |
## Implementation Notes
The connector supports multiple regional API endpoints:
* **Global (SEA)**: Singapore, Malaysia, Thailand, Vietnam, Philippines, Indonesia, Taiwan
* **Brazil**: Specific endpoint for Brazilian marketplace
* **China**: Mainland China operations
Make sure to select the correct API URL for your shop's region.
The connector supports incremental sync for daily performance data:
* **Ads Daily Product Campaign Performance**: Uses `date` as the replication key
Campaign list and campaign settings are synced as full table since they represent current state.
This connector uses the same authentication mechanism as the Shopee connector:
* Access tokens are refreshed proactively 30 minutes before expiration
* Every API request is signed with HMAC-SHA256 using your Partner Key
* Refresh tokens are stored securely in the Meltano database
* Token expiration defaults to 4 hours if not specified by the API
Shopee Ads uses a 7-day attribution window for conversion metrics:
* **Broad attribution**: Counts orders for any product in your shop within 7 days of an ad click
* **Direct attribution**: Counts orders only for the specific advertised product within 7 days
Both broad and direct metrics are available in the daily performance stream.
The connector fetches campaign IDs first, then batches them (up to 50 per request) to retrieve campaign details and performance data. This approach minimizes API calls while respecting Shopee's API rate limits.
## Skills for agents
Shopee Ads connector documentation as plain markdown, for use in AI agent contexts.