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_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.py
index 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.set
INCREMENTAL_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_16
api_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_value
if inputs.should_use_incremental_field
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/square/square.py b/products/warehouse_sources/backend/temporal/data_imports/sources/square/square.py
index 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 requests
from structlog.types import FilteringBoundLogger
from 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_session
from products.warehouse_sources.backend.temporal.data_imports.sources.common.resumable import ResumableSourceManager
from 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.set
SquareEndpointConfig,
)
-# 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.dataclass
class 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 accept
scope 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: Optio
url = 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.py
index 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.set
from products.warehouse_sources.backend.temporal.data_imports.sources.square.source import SquareSource
from 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) == expected
def 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_header
class 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 the
diff --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.py
index 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 mock
from products.warehouse_sources.backend.temporal.data_imports.sources.generated_configs.square import SquareSourceConfig
from products.warehouse_sources.backend.temporal.data_imports.sources.square.source import SquareSource
+from products.warehouse_sources.backend.temporal.data_imports.sources.square.square import SquareCredentialProbe
class 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_valid
assert (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
+ )