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.

fix(klaviyo): stop offering tables the pinned api revision does not serve (#118468)

Tom Owersa7f1f9c63aec
diff --git a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
index 0739df97bac4..a1ffb3423b8b 100644
--- a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
+++ b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
@@ -1435,7 +1435,7 @@
3 products/tasks/backend/temporal/build_image/activities.py
3 products/tasks/backend/temporal/process_task/activities/send_permission_response_to_sandbox.py
3 products/warehouse_sources/backend/temporal/data_imports/cdc/activities.py
-3 products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/settings.py
+2 products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/settings.py
3 products/warehouse_sources/backend/temporal/data_imports/sources/stripe/stripe.py
3 products/warehouse_sources/backend/temporal/data_imports/workflow_activities/acquire_v3_lock.py
3 products/web_analytics/backend/hogql_queries/external/summary_query_runner.py
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/klaviyo.py b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/klaviyo.py
index aed716e0ce83..846a698cea78 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/klaviyo.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/klaviyo.py
@@ -822,6 +822,11 @@ def klaviyo_source(
conversion_metric_id: str | None = None,
) -> SourceResponse:
endpoint_config = KLAVIYO_ENDPOINTS[endpoint]
+ if not endpoint_config.is_served_at(api_version):
+ raise ValueError(
+ f"Klaviyo table {endpoint} requires Klaviyo API version {', '.join(endpoint_config.api_versions or ())}, "
+ f"but this source is pinned to {api_version}"
+ )
return SourceResponse(
name=endpoint,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/settings.py
index 834dab6b6569..e74204837ac7 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/settings.py
@@ -4,6 +4,9 @@ from typing import Optional
from posthog.dataclasses import frozen
+from products.warehouse_sources.backend.temporal.data_imports.sources.klaviyo.constants import (
+ KLAVIYO_API_VERSION_2026_07_15,
+)
from products.warehouse_sources.backend.types import IncrementalField, IncrementalFieldType
@@ -84,7 +87,7 @@ class KlaviyoValuesReportConfig:
raise ValueError(f"{self.report_type}: {self.timeframe_key} is not a Klaviyo timeframe key")
-@dataclass
+@dataclass(frozen=False)
class KlaviyoEndpointConfig:
name: str
path: str
@@ -115,6 +118,12 @@ class KlaviyoEndpointConfig:
values_report: Optional[KlaviyoValuesReportConfig] = None
# Shown next to the table in the schema picker.
description: Optional[str] = None
+ # Revisions that serve this endpoint. None means every supported revision does. Klaviyo answers
+ # 404 for an endpoint added after the revision a source is pinned to.
+ api_versions: Optional[tuple[str, ...]] = None
+
+ def is_served_at(self, api_version: str) -> bool:
+ return self.api_versions is None or api_version in self.api_versions
# Every statistic Klaviyo's campaign and flow values reports accept. Both endpoints document the
@@ -741,6 +750,7 @@ KLAVIYO_ENDPOINTS: dict[str, KlaviyoEndpointConfig] = {
),
"web_feeds": KlaviyoEndpointConfig(
name="web_feeds",
+ api_versions=(KLAVIYO_API_VERSION_2026_07_15,),
path="/web-feeds",
default_incremental_field="updated",
partition_key="created",
@@ -827,6 +837,7 @@ KLAVIYO_ENDPOINTS: dict[str, KlaviyoEndpointConfig] = {
),
"data_sources": KlaviyoEndpointConfig(
name="data_sources",
+ api_versions=(KLAVIYO_API_VERSION_2026_07_15,),
path="/data-sources",
page_size=100,
incremental_fields=[],
@@ -835,12 +846,14 @@ KLAVIYO_ENDPOINTS: dict[str, KlaviyoEndpointConfig] = {
# through the cursor links Klaviyo returns.
"custom_metrics": KlaviyoEndpointConfig(
name="custom_metrics",
+ api_versions=(KLAVIYO_API_VERSION_2026_07_15,),
path="/custom-metrics",
page_size=0,
incremental_fields=[],
),
"object_types": KlaviyoEndpointConfig(
name="object_types",
+ api_versions=(KLAVIYO_API_VERSION_2026_07_15,),
path="/object-types",
page_size=0,
incremental_fields=[],
@@ -868,6 +881,7 @@ KLAVIYO_ENDPOINTS: dict[str, KlaviyoEndpointConfig] = {
# ["id"] primary key holds table-wide; object_type_id rides along as its own column for joins.
"custom_object_records": KlaviyoEndpointConfig(
name="custom_object_records",
+ api_versions=(KLAVIYO_API_VERSION_2026_07_15,),
path="/object-types/{object_type_id}/object-records",
page_size=100, # object-records caps page[size] at 100
incremental_fields=[],
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/source.py
index 84d934256e40..fb3f3c2c4305 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/source.py
@@ -42,6 +42,11 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.klaviyo.se
)
from products.warehouse_sources.backend.types import ExternalDataSourceType
+# Shown in the schema picker against a table the source's API version does not serve.
+KLAVIYO_NEWER_VERSION_REQUIRED = (
+ "Needs a newer Klaviyo API version than your source uses. Contact PostHog support to upgrade the source."
+)
+
@SourceRegistry.register
class KlaviyoSource(ResumableSource[KlaviyoSourceConfig, KlaviyoResumeConfig]):
@@ -183,6 +188,9 @@ The campaign and flow performance tables (campaign_values_reports, flow_values_r
# the per-request path/query/timestamp.
"401 Client Error: Unauthorized for url: https://a.klaviyo.com": "Your Klaviyo API key is invalid or has been revoked. Create a new private API key in your Klaviyo account settings, then reconnect.",
"403 Client Error: Forbidden for url: https://a.klaviyo.com": "Your Klaviyo API key is missing the read permissions needed to sync this data. Grant the required read scopes in your Klaviyo account settings, then reconnect.",
+ # Raised by klaviyo_source for a table the source's pinned revision does not serve. Moving a
+ # source to a newer revision is a support-run migration, so that is the next step.
+ "requires Klaviyo API version": "This table needs a newer Klaviyo API version than your source uses. Contact PostHog support to upgrade the source, then re-enable this table.",
}
def get_schemas(
@@ -205,16 +213,22 @@ The campaign and flow performance tables (campaign_values_reports, flow_values_r
if endpoint_config.incremental_lookback or endpoint_config.values_report is not None
}
+ resolved_version = self.resolve_api_version(api_version)
+
def _build_schema(endpoint: str) -> SourceSchema:
endpoint_config = KLAVIYO_ENDPOINTS[endpoint]
has_incremental = INCREMENTAL_FIELDS.get(endpoint, None) is not None
+ # A table the source's revision does not serve stays listed, because a schema-level version
+ # override can still sync it, and discovery disables any enabled table it stops listing.
+ # Default-off keeps auto-sync from enabling it into a sync that can only fail.
+ served = endpoint_config.is_served_at(resolved_version)
return SourceSchema(
name=endpoint,
supports_incremental=has_incremental and endpoint not in append_only_endpoints,
supports_append=has_incremental and endpoint not in merge_only_endpoints,
incremental_fields=INCREMENTAL_FIELDS.get(endpoint, []),
- should_sync_default=endpoint_config.should_sync_default,
- description=endpoint_config.description,
+ should_sync_default=endpoint_config.should_sync_default and served,
+ description=endpoint_config.description if served else KLAVIYO_NEWER_VERSION_REQUIRED,
)
schemas = [_build_schema(endpoint) for endpoint in ENDPOINTS]
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/test_klaviyo.py b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/test_klaviyo.py
index f1941e9eb93f..53b05a309468 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/test_klaviyo.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/klaviyo/test_klaviyo.py
@@ -44,7 +44,10 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.klaviyo.se
KlaviyoEndpointConfig,
KlaviyoValuesReportConfig,
)
-from products.warehouse_sources.backend.temporal.data_imports.sources.klaviyo.source import KlaviyoSource
+from products.warehouse_sources.backend.temporal.data_imports.sources.klaviyo.source import (
+ KLAVIYO_NEWER_VERSION_REQUIRED,
+ KlaviyoSource,
+)
def _driver(conversion_metric_id: str | None = None) -> SourceDriver:
@@ -982,6 +985,36 @@ class TestApiVersionThreadsToRevisionHeader:
assert result.requests[0].headers["revision"] == api_version
+class TestEndpointsNewerThanThePinnedRevision:
+ @parameterized.expand(
+ [
+ (KLAVIYO_API_VERSION_2024_10_15, False),
+ (KLAVIYO_API_VERSION_2026_07_15, True),
+ (None, True),
+ ]
+ )
+ def test_tables_the_pinned_revision_does_not_serve_stay_listed_but_default_off(
+ self, pin: str | None, served: bool
+ ) -> None:
+ schemas = {s.name: s for s in KlaviyoSource().get_schemas(MagicMock(), team_id=1, api_version=pin)}
+ assert schemas["events"].should_sync_default is True
+ for name in ("data_sources", "custom_metrics", "object_types", "custom_object_records", "web_feeds"):
+ assert schemas[name].should_sync_default is served
+ assert (schemas[name].description == KLAVIYO_NEWER_VERSION_REQUIRED) is not served
+
+ def test_enabled_table_on_an_older_pin_fails_without_calling_klaviyo(self) -> None:
+ result = _driver().run("data_sources", [], api_version=KLAVIYO_API_VERSION_2024_10_15)
+ assert result.raised is not None
+ assert result.requests == []
+ friendly = [
+ message
+ for pattern, message in KlaviyoSource().get_non_retryable_errors().items()
+ if error_message_matches(str(result.raised), [pattern])
+ ]
+ assert friendly and friendly[0] is not None
+ assert "Contact PostHog support" in friendly[0]
+
+
class TestValidateCredentialsResolvedPin:
@parameterized.expand(
[