Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(warehouse): import tiktok click-attributed web purchases (#121321)

Javier Bahamondes90da28f5b2d6
diff --git a/docs/published/handbook/engineering/data-warehouse.md b/docs/published/handbook/engineering/data-warehouse.md
index 689250828c87..d0dd25924220 100644
--- a/docs/published/handbook/engineering/data-warehouse.md
+++ b/docs/published/handbook/engineering/data-warehouse.md
@@ -352,6 +352,14 @@ The CTA fields describe app conversions and purchases attributed to clicks; they
The optional `advertiser_report` table requests daily `spend` and `cash_spend` at advertiser level.
Cash spend can arrive later than other performance metrics.
+TikTok Ads API v2.0 adds the optional `campaign_website_attribution_report`, `ad_group_website_attribution_report`, and `ad_website_attribution_report` tables.
+Select API v2.0 on the source and enable these tables to import `cta_complete_payment` (website purchases attributed to clicks) and `cta_complete_payment_value` (their purchase value).
+Existing report, audience, entity, and creative tables continue using v1.3 under either source version.
+The separate tables preserve the existing ad report IDs: in v2.0, `ad_id` identifies the ad asset group for Upgraded Smart+ campaigns rather than the legacy creative.
+Do not join that ID directly to legacy creative IDs for those campaigns.
+Existing v1.3 pins keep their table catalog until the source version changes; no automatic repin or historical backfill runs.
+The new tables use the advertiser account time zone and the same date-window, incremental, and resume behavior as other TikTok reports.
+
Reddit Ads requests purchase click and view counts, sign-up click counts, average purchase value, fully viewable video impressions, and viewable video impressions in its campaign, ad group, ad, and breakdown reports.
The conversion window still follows the account's attribution settings.
diff --git a/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py b/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py
index dff22c4435f4..cc8b46e584f4 100644
--- a/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py
+++ b/products/warehouse_sources/sources/tiktok_ads/canonical_descriptions.py
@@ -321,3 +321,27 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
),
},
}
+
+
+for report_name, dimension in {
+ "campaign_website_attribution_report": "campaign_id",
+ "ad_group_website_attribution_report": "adgroup_id",
+ "ad_website_attribution_report": "ad_id",
+}.items():
+ CANONICAL_DESCRIPTIONS[report_name] = {
+ "description": "Daily website purchases and purchase value, including conversions attributed to ad clicks. Requires API v2.0.",
+ "docs_url": "https://business-api.tiktok.com/portal/docs/run-a-synchronous-report/v2.0",
+ "columns": {
+ dimension: (
+ "Ad ID from Reporting API v2.0. For Upgraded Smart+ campaigns, this identifies the ad asset group rather than the legacy creative."
+ if dimension == "ad_id"
+ else "ID of the campaign or ad group the metrics belong to."
+ ),
+ "stat_time_day": "Date the metrics are aggregated for in the advertiser account time zone.",
+ "spend": "Total amount spent in the reporting period.",
+ "complete_payment": "Number of website purchase events attributed to the ads.",
+ "total_complete_payment_rate": "Total value of website purchase events attributed to the ads.",
+ "cta_complete_payment": "Number of website purchase events attributed to clicks on the ads.",
+ "cta_complete_payment_value": "Total value of website purchase events attributed to clicks on the ads.",
+ },
+ }
diff --git a/products/warehouse_sources/sources/tiktok_ads/settings.py b/products/warehouse_sources/sources/tiktok_ads/settings.py
index 99ae130f1b08..ba10ac6a50d4 100644
--- a/products/warehouse_sources/sources/tiktok_ads/settings.py
+++ b/products/warehouse_sources/sources/tiktok_ads/settings.py
@@ -12,7 +12,9 @@ from products.warehouse_sources.sources.sdk import (
)
MAX_TIKTOK_DAYS_TO_QUERY = 29
-BASE_URL = "https://business-api.tiktok.com/open_api/v1.3"
+TIKTOK_API_VERSION_V13 = "v1.3"
+TIKTOK_API_VERSION_V2 = "v2.0"
+BASE_URL = f"https://business-api.tiktok.com/open_api/{TIKTOK_API_VERSION_V13}"
MAX_TIKTOK_DAYS_FOR_REPORT_ENDPOINTS = 365
METRICS_FIELDS = [
@@ -573,3 +575,48 @@ TIKTOK_ADS_CONFIG: dict[str, EndpointConfig] = {
AD_AUDIENCE_REPORT_METRICS_FIELDS,
),
}
+
+
+WEBSITE_ATTRIBUTION_REPORTS = {
+ "campaign_website_attribution_report": "campaign_id",
+ "ad_group_website_attribution_report": "adgroup_id",
+ "ad_website_attribution_report": "ad_id",
+}
+
+for report_name, dimension in WEBSITE_ATTRIBUTION_REPORTS.items():
+ TIKTOK_ADS_CONFIG[report_name] = EndpointConfig(
+ resource={
+ "name": report_name,
+ "table_name": report_name,
+ "primary_key": [dimension, "stat_time_day"],
+ "endpoint": {
+ "path": f"https://business-api.tiktok.com/open_api/{TIKTOK_API_VERSION_V2}/report/integrated/get/",
+ "method": "GET",
+ "params": {
+ "advertiser_ids": json.dumps(["{advertiser_id}"]),
+ "dimensions": json.dumps([dimension, "stat_time_day"]),
+ "metrics": json.dumps(
+ [
+ "spend",
+ "complete_payment",
+ "total_complete_payment_rate",
+ "cta_complete_payment",
+ "cta_complete_payment_value",
+ ]
+ ),
+ "page_size": 1000,
+ "start_date": "{start_date}",
+ "end_date": "{end_date}",
+ "page": 1,
+ },
+ "data_selector": "data.list",
+ },
+ "table_format": "delta",
+ },
+ incremental_fields=[STAT_TIME_DAY_INCREMENTAL_FIELD],
+ partition_keys=["stat_time_day"],
+ partition_mode="datetime",
+ partition_format="week",
+ endpoint_type=EndpointType.REPORT,
+ should_sync_default=False,
+ )
diff --git a/products/warehouse_sources/sources/tiktok_ads/source.py b/products/warehouse_sources/sources/tiktok_ads/source.py
index a4b65fcd89b7..3ce539745859 100644
--- a/products/warehouse_sources/sources/tiktok_ads/source.py
+++ b/products/warehouse_sources/sources/tiktok_ads/source.py
@@ -26,7 +26,12 @@ from products.warehouse_sources.sources.sdk import (
detect,
)
from products.warehouse_sources.sources.tiktok_ads._config import TikTokAdsSourceConfig
-from products.warehouse_sources.sources.tiktok_ads.settings import TIKTOK_ADS_CONFIG
+from products.warehouse_sources.sources.tiktok_ads.settings import (
+ TIKTOK_ADS_CONFIG,
+ TIKTOK_API_VERSION_V2,
+ TIKTOK_API_VERSION_V13,
+ WEBSITE_ATTRIBUTION_REPORTS,
+)
from products.warehouse_sources.sources.tiktok_ads.tiktok_ads import TikTokAdsResumeConfig, tiktok_ads_source
from products.warehouse_sources.sources.tiktok_ads.utils import (
TIKTOK_APP_TOKEN_MISMATCH_MESSAGE,
@@ -43,6 +48,10 @@ from products.warehouse_sources.sources.tiktok_ads.utils import (
list_advertisers,
)
+WEBSITE_ATTRIBUTION_VERSION_ERROR = (
+ "Website attribution reports require TikTok Ads API v2.0. Change the source API version to v2.0."
+)
+
@SourceRegistry.register
class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConfig], OAuthMixin):
@@ -65,9 +74,9 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConf
swiftpm=("github.com/tiktok/tiktok-business-ios-sdk",),
)
- supported_versions = ("v1.3",)
- default_version = "v1.3"
- api_docs_url = "https://business-api.tiktok.com/portal/docs"
+ supported_versions = (TIKTOK_API_VERSION_V13, TIKTOK_API_VERSION_V2)
+ default_version = TIKTOK_API_VERSION_V2
+ api_docs_url = "https://business-api.tiktok.com/portal/docs/api-reference/v2.0"
lists_tables_without_credentials = True # static endpoint catalog — safe for public docs
@@ -95,6 +104,7 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConf
# prefix; retrying cannot recover, so fail the job fast. The raw message is kept as
# the user-facing error since it names the specific advertiser and TikTok error code.
TIKTOK_NON_RETRYABLE_ERROR_PREFIX: None,
+ WEBSITE_ATTRIBUTION_VERSION_ERROR: None,
# Integration row was deleted/disconnected while a scheduled job still references it.
# Raised by OAuthMixin.get_oauth_integration as `ValueError("Integration not found: <id>")`;
# the id is volatile, so match only the stable prefix. Retrying can't recreate the row —
@@ -252,7 +262,8 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConf
incremental_fields=endpoint_config.incremental_fields or [],
should_sync_default=endpoint_config.should_sync_default,
)
- for endpoint_config in TIKTOK_ADS_CONFIG.values()
+ for name, endpoint_config in TIKTOK_ADS_CONFIG.items()
+ if name not in WEBSITE_ATTRIBUTION_REPORTS or self.resolve_api_version(api_version) == TIKTOK_API_VERSION_V2
]
if names is not None:
names_set = set(names)
@@ -268,6 +279,12 @@ class TikTokAdsSource(ResumableSource[TikTokAdsSourceConfig, TikTokAdsResumeConf
resumable_source_manager: ResumableSourceManager[TikTokAdsResumeConfig],
inputs: SourceInputs,
) -> SourceResponse:
+ if (
+ inputs.schema_name in WEBSITE_ATTRIBUTION_REPORTS
+ and self.resolve_api_version(inputs.api_version) != TIKTOK_API_VERSION_V2
+ ):
+ raise ValueError(WEBSITE_ATTRIBUTION_VERSION_ERROR)
+
integration = self.get_oauth_integration(config.tiktok_integration_id, inputs.team_id)
if not integration.access_token:
diff --git a/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py b/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py
index 78ae3353b2cb..309753d0aa15 100644
--- a/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py
+++ b/products/warehouse_sources/sources/tiktok_ads/test/test_tiktok_ads.py
@@ -1,3 +1,4 @@
+import json
from datetime import datetime, timedelta
from typing import Any
@@ -407,3 +408,109 @@ class TestTikTokAdsTransientErrorRetry:
assert isinstance(result.raised, ValueError)
assert "non-retryable" in str(result.raised)
assert len(result.requests) == 1
+
+
+ ("endpoint", "dimension"),
+ [
+ ("campaign_website_attribution_report", "campaign_id"),
+ ("ad_group_website_attribution_report", "adgroup_id"),
+ ("ad_website_attribution_report", "ad_id"),
+ ],
+)
+def test_website_attribution_reports_paginate_and_flatten(endpoint: str, dimension: str) -> None:
+ day = datetime.now().strftime("%Y-%m-%d")
+ result = _drive(
+ endpoint,
+ [
+ _page_response(
+ 1,
+ 2,
+ [
+ {
+ "dimensions": {dimension: "101", "stat_time_day": day},
+ "metrics": {"cta_complete_payment": "2", "cta_complete_payment_value": "48.25"},
+ }
+ ],
+ ),
+ _page_response(
+ 2,
+ 2,
+ [
+ {
+ "dimensions": {dimension: "102", "stat_time_day": day},
+ "metrics": {"cta_complete_payment": "0", "cta_complete_payment_value": "0.00"},
+ }
+ ],
+ ),
+ ],
+ api_version="v2.0",
+ incremental_field="stat_time_day",
+ db_incremental_field_last_value=day,
+ )
+ assert result.raised is None
+ assert result.rows == [
+ {dimension: "101", "stat_time_day": day, "cta_complete_payment": "2", "cta_complete_payment_value": "48.25"},
+ {dimension: "102", "stat_time_day": day, "cta_complete_payment": "0", "cta_complete_payment_value": "0.00"},
+ ]
+ assert result.params("page") == ["1", "2"]
+ for request in result.requests:
+ assert request.url.startswith("https://business-api.tiktok.com/open_api/v2.0/report/integrated/get/")
+ advertiser_ids = request.param("advertiser_ids")
+ dimensions = request.param("dimensions")
+ metrics = request.param("metrics")
+ assert advertiser_ids is not None and dimensions is not None and metrics is not None
+ assert json.loads(advertiser_ids) == [ADVERTISER_ID]
+ assert json.loads(dimensions) == [dimension, "stat_time_day"]
+ assert {"cta_complete_payment", "cta_complete_payment_value"} <= set(json.loads(metrics))
+ assert request.param("advertiser_id") is None
+ assert request.param("report_type") is None
+ assert request.param("data_level") is None
+ start_date, end_date = request.param("start_date"), request.param("end_date")
+ assert start_date is not None and end_date is not None
+ assert start_date <= day <= end_date
+ assert result.saved_states[0].page == 2
+
+
+def test_website_attribution_report_rejects_legacy_pin() -> None:
+ result = _drive("campaign_website_attribution_report", [], api_version="v1.3")
+ assert isinstance(result.raised, ValueError)
+ assert "Change the source API version to v2.0" in str(result.raised)
+ assert result.requests == []
+
+
[email protected]("api_version", ["v1.3", "v2.0"])
+def test_legacy_ad_reports_keep_their_request_and_identifiers(api_version: str) -> None:
+ day = datetime.now().strftime("%Y-%m-%d")
+ result = _drive(
+ "ad_report",
+ [
+ _page_response(
+ 1, 1, [{"dimensions": {"ad_id": "legacy-creative", "stat_time_day": day}, "metrics": {"spend": "1.00"}}]
+ )
+ ],
+ api_version=api_version,
+ incremental_field="stat_time_day",
+ db_incremental_field_last_value=day,
+ )
+ assert result.raised is None
+ assert result.rows[0]["ad_id"] == "legacy-creative"
+ request = result.requests[0]
+ assert request.url.startswith("https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/")
+ assert request.param("advertiser_id") == ADVERTISER_ID
+ assert request.param("advertiser_ids") is None
+ assert request.param("report_type") == "BASIC"
+ assert request.param("data_level") == "AUCTION_AD"
+
+
[email protected](("api_version", "website_reports_available"), [("v1.3", False), ("v2.0", True)])
+def test_source_discovery_honors_the_version_pin(api_version: str, website_reports_available: bool) -> None:
+ schemas = TikTokAdsSource().get_schemas(
+ TikTokAdsSourceConfig(advertiser_id=ADVERTISER_ID, tiktok_integration_id=1),
+ team_id=1,
+ api_version=api_version,
+ names=["campaign_report", "campaign_website_attribution_report"],
+ )
+ names = {schema.name for schema in schemas}
+ assert "campaign_report" in names
+ assert ("campaign_website_attribution_report" in names) == website_reports_available