: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(warehouse_sources): support square api version 2026-09-16 (#119198)
Tom Owers78dfaf9d27fa
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/square/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/square/source.pyindex 789ac2bd5741..8119b4f709b2 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/square/source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/square/source.py@@ -24,6 +24,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.square.setINCREMENTAL_FIELDS,)from products.warehouse_sources.backend.temporal.data_imports.sources.square.square import (+ SQUARE_API_VERSION_2026_09_16,+ SQUARE_API_VERSION_V2,SquareResumeConfig,square_source,validate_credentials as validate_square_credentials,@@ -47,8 +49,8 @@ class SquareSource(ResumableSource[SquareSourceConfig, SquareResumeConfig]):swiftpm=("github.com/square/squarepointofsalesdk-ios",),)- supported_versions = ("v2",)- default_version = "v2"+ supported_versions = (SQUARE_API_VERSION_V2, SQUARE_API_VERSION_2026_09_16)+ default_version = SQUARE_API_VERSION_2026_09_16api_docs_url = "https://developer.squareup.com/docs"lists_tables_without_credentials = True # static endpoint catalog — safe for public docs@@ -156,18 +158,20 @@ Grant these read permissions to the token for the data you want to sync:schema_name: Optional[str] = None,api_version: str | None = None,) -> tuple[bool, str | None]:- is_valid, is_forbidden = validate_square_credentials(config.access_token, config.environment, schema_name)- if is_valid:+ probe = validate_square_credentials(+ config.access_token, config.environment, self.resolve_api_version(api_version), schema_name+ )+ if probe.is_valid:return True, None# A 403 means the token is genuine but lacks the scope for this endpoint.# Accept that at source-create (schema_name=None) — users may only grant# scopes for the endpoints they intend to sync — and reject only when# validating a specific schema.- if is_forbidden and schema_name is None:+ if probe.is_forbidden and schema_name is None:return True, None- if is_forbidden:+ if probe.is_forbidden:return False, f"The Square access token is missing the permission required to sync '{schema_name}'"return False, "Invalid Square access token"@@ -187,6 +191,7 @@ Grant these read permissions to the token for the data you want to sync:endpoint=inputs.schema_name,logger=inputs.logger,resumable_source_manager=resumable_source_manager,+ api_version=self.resolve_api_version(inputs.api_version),should_use_incremental_field=inputs.should_use_incremental_field,db_incremental_field_last_value=inputs.db_incremental_field_last_valueif inputs.should_use_incremental_fielddiff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/square/square.py b/products/warehouse_sources/backend/temporal/data_imports/sources/square/square.pyindex 77da796c8fc5..2219acd80b28 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/square/square.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/square/square.py@@ -8,6 +8,8 @@ import requestsfrom structlog.types import FilteringBoundLoggerfrom tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential_jitter+from posthog.dataclasses import frozen+from products.warehouse_sources.backend.temporal.data_imports.sources.common.http import make_tracked_sessionfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.resumable import ResumableSourceManagerfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.typings import SourceResponse@@ -16,9 +18,16 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.square.setSquareEndpointConfig,)-# Square pins API behaviour to a dated version header. Bump deliberately after-# re-reading the changelog — newer versions can reshape responses.-SQUARE_API_VERSION = "2024-10-17"+SQUARE_API_VERSION_V2 = "v2"+SQUARE_API_VERSION_2026_09_16 = "2026-09-16"++# Square pins API behaviour to a dated version header. Add new versions deliberately+# after re-reading the changelog — newer versions can reshape responses. The legacy+# "v2" label predates per-version pins and keeps sending the header it always sent.+SQUARE_VERSION_HEADERS: dict[str, str] = {+ SQUARE_API_VERSION_V2: "2024-10-17",+ SQUARE_API_VERSION_2026_09_16: "2026-09-16",+}SQUARE_HOSTS = {"production": "https://connect.squareup.com",@@ -61,6 +70,13 @@ def _is_invalid_cursor_error(response: requests.Response) -> bool:return any(error.get("field") == "cursor" or error.get("code") == "INVALID_CURSOR" for error in errors)+@frozen+class SquareCredentialProbe:+ is_valid: bool+ # A 403 (valid token, missing scope) as opposed to a 401 (bad token).+ is_forbidden: bool++@dataclasses.dataclassclass SquareResumeConfig:# The next-page pagination cursor returned by Square. Square cursors expire@@ -73,10 +89,13 @@ def _base_url(environment: str) -> str:return SQUARE_HOSTS.get(environment, SQUARE_HOSTS["production"])-def _get_headers(access_token: str) -> dict[str, str]:+def _get_headers(access_token: str, api_version: str) -> dict[str, str]:+ square_version = SQUARE_VERSION_HEADERS.get(api_version)+ if square_version is None:+ raise ValueError(f"Unsupported Square API version: {api_version}")return {"Authorization": f"Bearer {access_token}",- "Square-Version": SQUARE_API_VERSION,+ "Square-Version": square_version,"Accept": "application/json",}@@ -116,10 +135,12 @@ def _time_filter_field(config: SquareEndpointConfig) -> Optional[str]:return config.incremental_fields[0]["field"]-def validate_credentials(access_token: str, environment: str, schema_name: Optional[str] = None) -> tuple[bool, bool]:+def validate_credentials(+ access_token: str, environment: str, api_version: str, schema_name: Optional[str] = None+) -> SquareCredentialProbe:"""Probe Square to confirm the token works.- Returns ``(is_valid, is_forbidden)``. ``is_forbidden`` distinguishes a 403+ ``is_forbidden`` on the result distinguishes a 403(valid token, missing scope) from a 401 (bad token) so the caller can acceptscope gaps at source-create time but reject them for a specific schema."""@@ -135,16 +156,17 @@ def validate_credentials(access_token: str, environment: str, schema_name: Optiourl = f"{_base_url(environment)}{path}"if params:url = f"{url}?{urlencode(params)}"+ headers = _get_headers(access_token, api_version)try:- response = make_tracked_session().get(url, headers=_get_headers(access_token), timeout=REQUEST_TIMEOUT_SECONDS)+ response = make_tracked_session().get(url, headers=headers, timeout=REQUEST_TIMEOUT_SECONDS)except Exception:- return False, False+ return SquareCredentialProbe(is_valid=False, is_forbidden=False)if response.status_code == 403:- return False, True+ return SquareCredentialProbe(is_valid=False, is_forbidden=True)- return response.status_code == 200, False+ return SquareCredentialProbe(is_valid=response.status_code == 200, is_forbidden=False)def get_rows(@@ -153,11 +175,12 @@ def get_rows(endpoint: str,logger: FilteringBoundLogger,resumable_source_manager: ResumableSourceManager[SquareResumeConfig],+ api_version: str,should_use_incremental_field: bool = False,db_incremental_field_last_value: Any = None,) -> Iterator[list[dict[str, Any]]]:config = SQUARE_ENDPOINTS[endpoint]- headers = _get_headers(access_token)+ headers = _get_headers(access_token, api_version)url = f"{_base_url(environment)}{config.path}"initial_params = _build_initial_params(config, should_use_incremental_field, db_incremental_field_last_value)@@ -259,6 +282,7 @@ def square_source(endpoint: str,logger: FilteringBoundLogger,resumable_source_manager: ResumableSourceManager[SquareResumeConfig],+ api_version: str,should_use_incremental_field: bool = False,db_incremental_field_last_value: Optional[Any] = None,) -> SourceResponse:@@ -272,6 +296,7 @@ def square_source(endpoint=endpoint,logger=logger,resumable_source_manager=resumable_source_manager,+ api_version=api_version,should_use_incremental_field=should_use_incremental_field,db_incremental_field_last_value=db_incremental_field_last_value,),diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square.py b/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square.pyindex 8e2b58a8e890..38ba310064f1 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square.py@@ -17,7 +17,10 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.square.setfrom products.warehouse_sources.backend.temporal.data_imports.sources.square.source import SquareSourcefrom products.warehouse_sources.backend.temporal.data_imports.sources.square.square import (MAX_CURSOR_RESTARTS,+ SQUARE_API_VERSION_2026_09_16,+ SQUARE_API_VERSION_V2,SQUARE_HOSTS,+ SquareCredentialProbe,SquareInvalidCursorError,SquareResumeConfig,_build_initial_params,@@ -143,38 +146,74 @@ class TestIsInvalidCursorError:class TestValidateCredentials:@parameterized.expand([- ("ok", 200, (True, False)),- ("unauthorized", 401, (False, False)),- ("forbidden", 403, (False, True)),- ("server_error", 500, (False, False)),+ ("ok", 200, SquareCredentialProbe(is_valid=True, is_forbidden=False)),+ ("unauthorized", 401, SquareCredentialProbe(is_valid=False, is_forbidden=False)),+ ("forbidden", 403, SquareCredentialProbe(is_valid=False, is_forbidden=True)),+ ("server_error", 500, SquareCredentialProbe(is_valid=False, is_forbidden=False)),])- def test_status_code_mapping(self, _name: str, status_code: int, expected: tuple[bool, bool]) -> None:+ def test_status_code_mapping(self, _name: str, status_code: int, expected: SquareCredentialProbe) -> None:with scripted_network(always(_page({}, status_code=status_code))):- assert validate_credentials("token", "production") == expected+ assert validate_credentials("token", "production", SQUARE_API_VERSION_2026_09_16) == expecteddef test_network_error_returns_invalid(self) -> None:with scripted_network(always(ConnectionError("boom"))):- assert validate_credentials("token", "production") == (False, False)+ assert validate_credentials("token", "production", SQUARE_API_VERSION_2026_09_16) == SquareCredentialProbe(+ is_valid=False, is_forbidden=False+ )- def test_schema_probes_that_endpoint(self) -> None:+ @parameterized.expand(+ [+ ("legacy_v2", SQUARE_API_VERSION_V2, "2024-10-17"),+ ("2026_09_16", SQUARE_API_VERSION_2026_09_16, "2026-09-16"),+ ]+ )+ def test_schema_probes_that_endpoint(self, _name: str, api_version: str, expected_header: str) -> None:with scripted_network([_page({})]) as network:- validate_credentials("token", "sandbox", schema_name="payments")- assert network.requests_log[0].url.startswith(f"{SQUARE_HOSTS['sandbox']}/v2/payments")+ validate_credentials("token", "sandbox", api_version, schema_name="payments")+ request = network.requests_log[0]+ assert request.url.startswith(f"{SQUARE_HOSTS['sandbox']}/v2/payments")+ assert request.headers["square-version"] == expected_headerclass TestGetRowsPagination:def _drive(- self, endpoint: str, script: list[ScriptedResponse], resume_state: SquareResumeConfig | None = None+ self,+ endpoint: str,+ script: list[ScriptedResponse],+ resume_state: SquareResumeConfig | None = None,+ api_version: str | None = None,) -> DriveResult:config = SquareSourceConfig(access_token="token", environment="production")- return SourceDriver(SquareSource(), config).run(endpoint, script, resume_state=resume_state)+ return SourceDriver(SquareSource(), config).run(+ endpoint, script, resume_state=resume_state, api_version=api_version+ )def test_first_request_starts_unresumed_when_there_is_no_saved_state(self) -> None:result = self._drive("payments", [_page({"payments": [{"id": "a"}]})])assert result.requests[0].param("cursor") is None+ @parameterized.expand(+ [+ ("unpinned_uses_default", None, "2026-09-16"),+ ("legacy_v2_pin", SQUARE_API_VERSION_V2, "2024-10-17"),+ ("2026_09_16_pin", SQUARE_API_VERSION_2026_09_16, "2026-09-16"),+ ]+ )+ def test_sends_square_version_header_for_pin(+ self, _name: str, api_version: str | None, expected_header: str+ ) -> None:+ result = self._drive(+ "customers",+ [_page({"customers": [{"id": "c1"}], "cursor": "cur-1"}), _page({"customers": [{"id": "c2"}]})],+ api_version=api_version,+ )++ assert result.raised is None+ assert [request.path for request in result.requests] == ["/v2/customers", "/v2/customers"]+ assert {request.headers["square-version"] for request in result.requests} == {expected_header}+def test_invalid_cursor_resumes_incremental_endpoint_from_last_seen(self) -> None:# An endpoint with a server-side time filter (payments has begin_time) must not# re-scan from zero when a cursor expires mid-stream — it should re-issue thediff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square_source.pyindex 07f6bec228b4..9c8cc3056273 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square_source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/square/test_square_source.py@@ -3,6 +3,7 @@ from unittest import mockfrom products.warehouse_sources.backend.temporal.data_imports.sources.generated_configs.square import SquareSourceConfigfrom products.warehouse_sources.backend.temporal.data_imports.sources.square.source import SquareSource+from products.warehouse_sources.backend.temporal.data_imports.sources.square.square import SquareCredentialProbeclass TestSquareSource:@@ -17,12 +18,13 @@ class TestSquareSource:assert schemas[0].name == "payments"@pytest.mark.parametrize(- "mock_return, schema_name, expected_valid, expected_has_message",+ "mock_return, schema_name, api_version, expected_valid, expected_has_message, expected_version",[- ((True, False), None, True, False),- ((False, False), None, False, True), # 401 bad token- ((False, True), None, True, False), # 403 at source-create -> accepted- ((False, True), "payments", False, True), # 403 for a specific schema -> rejected+ ((True, False), None, None, True, False, "2026-09-16"), # pre-creation probe -> default version+ ((True, False), "payments", "v2", True, False, "v2"), # pinned row -> its own version+ ((False, False), None, None, False, True, "2026-09-16"), # 401 bad token+ ((False, True), None, None, True, False, "2026-09-16"), # 403 at source-create -> accepted+ ((False, True), "payments", None, False, True, "2026-09-16"), # 403 for a specific schema -> rejected],)@mock.patch(@@ -33,11 +35,17 @@ class TestSquareSource:mock_validate: mock.MagicMock,mock_return: tuple[bool, bool],schema_name: str | None,+ api_version: str | None,expected_valid: bool,expected_has_message: bool,+ expected_version: str,) -> None:- mock_validate.return_value = mock_return- is_valid, message = self.source.validate_credentials(self.config, self.team_id, schema_name=schema_name)+ mock_validate.return_value = SquareCredentialProbe(is_valid=mock_return[0], is_forbidden=mock_return[1])+ is_valid, message = self.source.validate_credentials(+ self.config, self.team_id, schema_name=schema_name, api_version=api_version+ )assert is_valid is expected_validassert (message is not None) is expected_has_message- mock_validate.assert_called_once_with(self.config.access_token, self.config.environment, schema_name)+ mock_validate.assert_called_once_with(+ self.config.access_token, self.config.environment, expected_version, schema_name+ )