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 Stripe API version 2026-10-28.endive (#126965)

Tom Owersb4a502d37dee
diff --git a/.agents/skills/warehouse-source-new-version/SKILL.md b/.agents/skills/warehouse-source-new-version/SKILL.md
index 637bafceca4c..ef7a36b7f60c 100644
--- a/.agents/skills/warehouse-source-new-version/SKILL.md
+++ b/.agents/skills/warehouse-source-new-version/SKILL.md
@@ -62,7 +62,7 @@ The opposite gap also occurs: a reference rendered from one version-blind OpenAP
- When the new version renames endpoints, changes primary keys, or reshapes responses, the divergence must actually be branched — never leave the old single-version request path serving the new default. All the relevant surfaces can vary by version: `get_rows` receives the resolved pin in `inputs.api_version`; credential fields can key off `default_version`.
- Conversely, don't add inert scaffolding: an `api_version` param no caller varies, or a version→URL map with identical values, is a review finding, not forward-compat. Declaration-only (`supported_versions`/`default_version` and nothing else) is the correct shape just when the gate above passed on a non-wire reason — the old label is being retired, the vendor switches behavior account-side rather than per request, or the source already reads the vendor's newest generation under the framework's legacy unversioned label (verify the request paths the source actually builds, not the label — a legacy label can already ride the new wire, so the new label just formalizes it for new rows and both resolve identically). If the gate passed on nothing at all, there is no PR. When no-header requests resolve to a version bound to the credential account-side (not a moving "latest"), threading a version header is not merely inert — it overrides the customer's chosen version, the silent move this framework exists to prevent — so stay declaration-only and don't send one.
- **Discovery and probe paths receive the pin — consume it.** The framework passes the resolved pin as the `api_version` parameter of `get_schemas`, `validate_credentials`, `get_endpoint_permissions`, and the webhook management methods. A multi-version source MUST build its discovery/probe/webhook clients from that parameter, not from `default_version` or a hardcoded header — otherwise a pinned source discovers/reconciles under the wrong version and its tables can disappear, duplicate, or fail reconciliation. Resolve it with `self.resolve_api_version(api_version)` — callers with a row pass an already-resolved value (mirroring `SourceInputs.api_version`), so the source-side resolve only covers pre-creation calls that pass `None`. Ignoring the parameter is only correct when you can state why the version makes no difference to that path.
- - Watch for version-dependent column hints/schemas: e.g. Stripe's `external_table_definitions` were built for specific versions. When adding a version whose response shapes differ, gate the canonical column hints to the versions they were built for and let newer versions auto-infer the schema from the data (a set of hint-compatible versions checked where hints are applied). For `has_managed_hogql_schema=True` sources this includes the read path: `hogql_definition`'s canonical column mapping is version-blind, so renamed columns need the canonical schema/descriptions updated too.
+ - Watch for version-dependent column hints/schemas: e.g. Stripe's `external_table_definitions` were built for specific versions. When adding a version whose response shapes differ, gate the canonical column hints to the versions they were built for and let newer versions auto-infer the schema from the data (a set of hint-compatible versions checked where hints are applied). For `has_managed_hogql_schema=True` sources this includes the read path: `hogql_definition`'s canonical column mapping is version-blind, so renamed columns need the canonical schema/descriptions updated too. Check what the hints do before gating them: where they only add absent columns as typed nulls (`_handle_null_columns_with_definitions`), a managed schema whose curated fields, or legacy-to-relocated fallbacks, reference those columns needs them on every version, because a curated field over an absent column is dropped and every downstream reader of it fails.
4. **Keep old versions working**: do not delete or alter the request path for previously supported versions. Removing a version is an explicit future decision, not part of a version-add PR.
5. **Tests**: extend the source's tests so both the old and new versions are exercised — at minimum that the version label reaches the client/request layer for each supported version (mock the boundary; parameterize over versions). The registry invariant test picks up declaration mistakes automatically. Don't re-test the base-class `resolve_api_version` contract (`test_source_versions.py` covers every source). When versions diverge, shape fixtures per version from the vendor docs — a v1-shaped mock under a v2 pin proves nothing. A test that passes no `api_version` runs on the default, so a default flip moves every existing legacy-path test onto the new path, where it fails or silently tests the wrong wire. Pin those tests to the old label explicitly.
6. **One PR per source.** Conventional title: `feat(warehouse_sources): support <vendor> API version <label>` — the scope is always `warehouse_sources` (the product), never the source dir/vendor name.
@@ -106,6 +106,7 @@ The opposite gap also occurs: a reference rendered from one version-blind OpenAP
- Don't regenerate schemas for existing customers as part of a version add; schema changes only apply to rows repinned via the (human-run) migration.
- Discovery diffs under the SOURCE pin (`sync_new_schemas`, `refresh_schemas`, bulk sync-defaults). A schema-level `api_version` override on a version whose table set differs from the source's version can be disabled/soft-deleted by that diff — keep overrides to short verification windows, not as a long-term way to hold one table on another version.
- When a versioned source sends the pin on any vendor call — discovery _or_ sync (a static endpoint catalog doesn't consume it at discovery, but `get_rows` still sends the version header) — add the vendor's version-rejection error signature (e.g. `406`/`410`) to `get_non_retryable_errors`, otherwise a retired pin turns the retry cadence into a permanent error loop with no user-facing surface.
+- A new version can bring endpoints from a newer API generation of the same vendor (a `/v2/` namespace) with a different list envelope. Check the request layer's response-shape guards (list markers, truncation or corrupt-body retries) against that envelope: a guard keyed on the old marker classifies every new response as corrupt and repeats each request.
- When the vendor rejects a retired version with a generic status (a plain `404`), its signature also matches every other 404 from that host. Add it only when every URL the source requests is static (list endpoints, no per-id or user-supplied paths), so a 404 can only mean the version, and say so in a comment next to the entry.
- A vendor that falls forward on a retired pin — serving the oldest accessible version instead of rejecting the request — has no rejection signature to add. Its sunset still needs the repin migration: the pin silently stops being honored, with no failed sync to surface it.
- A version bump can change the auth scheme, not just the wire format. Then the source config needs both credential shapes as optional fields, auth construction dispatches on the resolved version, and `validate_credentials` enforces the pair that version needs — form-level `required` can't express "depends on the pin".
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index 00e2e87c8dd2..5e6bd03aa737 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -11823,6 +11823,19 @@ Diffed against: <https://dev.streamelements.com/api/v1/projects/cHJqOjM1MTI2/tab
Note: The Stoplight docs render entirely client-side, so the resource list had to be pulled from the vendor's own table-of-contents API (project cHJqOjM1MTI2, found via a web.archive.org CDX listing of dev.streamelements.com). The legacy developers.streamelements.com host no longer resolves. Existence of the sessions, songrequest, contests, stats and themes routes was independently confirmed by unauthenticated probes of api.streamelements.com/kappa/v2 returning 401/200 rather than 404. Config surfaces (overlays, themes, filters, modules, loyalty settings) were excluded.
+## Stripe — gaps
+
+The API v1 coverage is tracked in [COVERAGE_GAPS.md](COVERAGE_GAPS.md).
+The lines below cover the API v2 money-management lists that Stripe published in `2026-10-28.endive`.
+These tables sync only on sources pinned to that version.
+
+Diffed against: <https://docs.stripe.com/api/v2/money-management/outbound-payments/list?api-version=2026-10-28.endive>
+
+- [x] `GET /v2/money_management/outbound_payments` — money sent from a financial account to a recipient's payout method (medium)
+- [x] `GET /v2/money_management/payout_intents` — multi-step payouts with fees, FX quotes and recipient checks (medium)
+- [x] `GET /v2/money_management/received_credits` — funds received into a financial account (medium)
+- [x] `GET /v2/money_management/inbound_transfers` — funds pulled from an external bank account into a financial account (medium)
+
## Stytch — gaps
Today (4): `members`, `organizations`, `sessions`, `users`
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/canonical_descriptions.py
index 8a7cefe6242d..05b18cf4c1c7 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/canonical_descriptions.py
@@ -30,17 +30,21 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.con
ENTITLEMENTS_ACTIVE_ENTITLEMENT_RESOURCE_NAME,
ENTITLEMENTS_FEATURE_RESOURCE_NAME,
EVENT_RESOURCE_NAME,
+ INBOUND_TRANSFER_RESOURCE_NAME,
INVOICE_ITEM_RESOURCE_NAME,
INVOICE_PAYMENT_RESOURCE_NAME,
INVOICE_RESOURCE_NAME,
+ OUTBOUND_PAYMENT_RESOURCE_NAME,
PAYMENT_INTENT_RESOURCE_NAME,
PAYMENT_LINK_RESOURCE_NAME,
+ PAYOUT_INTENT_RESOURCE_NAME,
PAYOUT_RESOURCE_NAME,
PLAN_RESOURCE_NAME,
PRICE_RESOURCE_NAME,
PRODUCT_RESOURCE_NAME,
PROMOTION_CODE_RESOURCE_NAME,
QUOTE_RESOURCE_NAME,
+ RECEIVED_CREDIT_RESOURCE_NAME,
REFUND_RESOURCE_NAME,
REVIEW_RESOURCE_NAME,
SETUP_ATTEMPT_RESOURCE_NAME,
@@ -75,6 +79,15 @@ def _columns(**overrides: str) -> dict[str, str]:
return {**_COMMON_COLUMNS, **overrides}
+# API v2 objects render `created` as an RFC 3339 string, not a Unix timestamp.
+_V2_COMMON_COLUMNS = {
+ "id": _COMMON_COLUMNS["id"],
+ "object": "String describing the object's Stripe type (e.g. 'v2.money_management.outbound_payment').",
+ "created": "Time at which the object was created, as an RFC 3339 timestamp.",
+ "livemode": _COMMON_COLUMNS["livemode"],
+}
+
+
CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
CHARGE_RESOURCE_NAME: {
"description": "A single attempt to move money into your Stripe account by charging a payment source.",
@@ -776,4 +789,81 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
tax_code="Tax code ID for the shipping rate.",
),
},
+ OUTBOUND_PAYMENT_RESOURCE_NAME: {
+ "description": "A money movement from one of your financial accounts to a payout method that someone else owns.",
+ "docs_url": "https://docs.stripe.com/api/v2/money-management/outbound-payments",
+ "columns": {
+ **_V2_COMMON_COLUMNS,
+ "metadata": _COMMON_COLUMNS["metadata"],
+ "amount": "Amount and currency requested for the payment, in the smallest currency unit.",
+ "from": "The financial account the funds came from, and the amount debited from it.",
+ "to": "The recipient and payout method the funds went to, and the amount credited.",
+ "status": "Current status: processing, posted, failed, canceled or returned.",
+ "status_details": "Reason for a processing, failed or returned status.",
+ "status_transitions": "Timestamps of the payment's status changes.",
+ "cancelable": "Whether the payment can still be canceled.",
+ "description": "Free-form text attached to the payment.",
+ "statement_descriptor": "Text shown on the recipient's bank statement.",
+ "expected_arrival_date": "Date the funds are expected to arrive at the payout method.",
+ "payout_intent": "ID of the payout intent that created this payment, if any.",
+ "recipient_notification": "Whether Stripe notifies the recipient about the payment.",
+ "recipient_verification": "ID of the recipient verification for this payment, if any.",
+ "tracking_details": "Details to trace the payment with the recipient's bank or card network.",
+ "receipt_url": "URL of the payment's receipt.",
+ },
+ },
+ PAYOUT_INTENT_RESOURCE_NAME: {
+ "description": "An intent to send funds from a financial account to a payout method, including fees and an FX quote.",
+ "docs_url": "https://docs.stripe.com/api/v2/money-management/payout-intents",
+ "columns": {
+ **_V2_COMMON_COLUMNS,
+ "metadata": _COMMON_COLUMNS["metadata"],
+ "amount": "Amount and currency to send, in the smallest currency unit.",
+ "from": "The financial account the funds come from, and the estimated amount debited.",
+ "to": "The recipient, payout method and currency the funds go to.",
+ "status": "Current status: requires_action, pending, processing, posted or canceled.",
+ "status_transitions": "Timestamps of the intent's status changes.",
+ "confirmation_method": "Whether the intent needs explicit confirmation before it proceeds.",
+ "description": "Free-form text attached to the intent.",
+ "statement_descriptor": "Text shown on the recipient's bank statement.",
+ "estimated_fees": "Estimated fees and taxes for the payout.",
+ "fx_quote": "Exchange rates quoted for the payout, and their lock status.",
+ "latest_payout": "The outbound payment or outbound transfer this intent last created.",
+ "next_action": "The action needed before the intent can proceed, when status is requires_action.",
+ "recipient_notification": "Whether Stripe notifies the recipient about the payout.",
+ "recipient_verification": "Result of the recipient name check, if one ran.",
+ "schedule_options": "Date the payout is scheduled to run, if it is not immediate.",
+ },
+ },
+ RECEIVED_CREDIT_RESOURCE_NAME: {
+ "description": "Funds received into one of your financial accounts, from a bank transfer or a Stripe balance transfer.",
+ "docs_url": "https://docs.stripe.com/api/v2/money-management/received-credits",
+ "columns": {
+ **_V2_COMMON_COLUMNS,
+ "amount": "Amount and currency credited to the financial account, in the smallest currency unit.",
+ "amount_received": "Amount and currency Stripe received, before any conversion or fees.",
+ "financial_account": "ID of the financial account that received the funds.",
+ "type": "How the funds arrived: bank_transfer or balance_transfer.",
+ "bank_transfer": "Details of the originating bank transfer, when type is bank_transfer.",
+ "balance_transfer": "Details of the originating Stripe money movement, when type is balance_transfer.",
+ "status": "Current status: pending, succeeded, failed or returned.",
+ "status_details": "Reason for a failed or returned status.",
+ "status_transitions": "Timestamps of the credit's status changes.",
+ "description": "Free-form text set by the sender.",
+ "receipt_url": "URL of the credit's receipt.",
+ },
+ },
+ INBOUND_TRANSFER_RESOURCE_NAME: {
+ "description": "A pull of funds from your own external bank account into one of your financial accounts.",
+ "docs_url": "https://docs.stripe.com/api/v2/money-management/inbound-transfers",
+ "columns": {
+ **_V2_COMMON_COLUMNS,
+ "amount": "Amount and currency that lands in the financial account, in the smallest currency unit.",
+ "from": "The bank account the funds were debited from, and the amount debited.",
+ "to": "The financial account the funds were credited to, and the amount credited.",
+ "transfer_history": "History entries of the transfer's state changes. The latest entry's type is its current status.",
+ "description": "Free-form text attached to the transfer.",
+ "receipt_url": "URL of the transfer's receipt.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/constants.py b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/constants.py
index e466ab4423c4..aff79720229d 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/constants.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/constants.py
@@ -42,10 +42,18 @@ TOPUP_RESOURCE_NAME = "Topup"
REVIEW_RESOURCE_NAME = "Review"
EARLY_FRAUD_WARNING_RESOURCE_NAME = "EarlyFraudWarning"
SHIPPING_RATE_RESOURCE_NAME = "ShippingRate"
+OUTBOUND_PAYMENT_RESOURCE_NAME = "OutboundPayment"
+PAYOUT_INTENT_RESOURCE_NAME = "PayoutIntent"
+RECEIVED_CREDIT_RESOURCE_NAME = "ReceivedCredit"
+INBOUND_TRANSFER_RESOURCE_NAME = "InboundTransfer"
# Vendor API version the sync pipeline pins by default. One constant so the source's version
# declaration (`StripeSource.supported_versions`) and the request layer share a single label.
STRIPE_API_VERSION_ACACIA = "2024-09-30.acacia"
+STRIPE_API_VERSION_ENDIVE = "2026-10-28.endive"
+
+# Versions that serve the API v2 money-management lists, which Stripe first published in 2026-10-28.endive.
+STRIPE_V2_MONEY_MANAGEMENT_VERSIONS = (STRIPE_API_VERSION_ENDIVE,)
# CustomerPaymentMethodHistory metadata columns. Every row is one observation of a payment
# method: either a `payment_method.*` webhook event, or a row from the initial attached-payment-
@@ -179,4 +187,6 @@ RESOURCE_TO_STRIPE_WEBHOOK_EVENT: dict[str, str] = {
# EntitlementsActiveEntitlement - the one entitlements event carries an
# `entitlements.active_entitlement_summary` object (a per-customer summary), not an
# individual active entitlement, so routing it here would write the wrong shape.
+ # OutboundPayment, PayoutIntent, ReceivedCredit, InboundTransfer - API v2 objects emit thin
+ # events to event destinations, never snapshot events to a webhook endpoint.
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/settings.py
index 9c32634ed502..b3d4c065d6ed 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/settings.py
@@ -29,17 +29,21 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.con
ENTITLEMENTS_FEATURE_RESOURCE_NAME,
EVENT_RESOURCE_NAME,
HISTORY_EVENT_ID_COLUMN,
+ INBOUND_TRANSFER_RESOURCE_NAME,
INVOICE_ITEM_RESOURCE_NAME,
INVOICE_PAYMENT_RESOURCE_NAME,
INVOICE_RESOURCE_NAME,
+ OUTBOUND_PAYMENT_RESOURCE_NAME,
PAYMENT_INTENT_RESOURCE_NAME,
PAYMENT_LINK_RESOURCE_NAME,
+ PAYOUT_INTENT_RESOURCE_NAME,
PAYOUT_RESOURCE_NAME,
PLAN_RESOURCE_NAME,
PRICE_RESOURCE_NAME,
PRODUCT_RESOURCE_NAME,
PROMOTION_CODE_RESOURCE_NAME,
QUOTE_RESOURCE_NAME,
+ RECEIVED_CREDIT_RESOURCE_NAME,
REFUND_RESOURCE_NAME,
REVIEW_RESOURCE_NAME,
SETUP_ATTEMPT_RESOURCE_NAME,
@@ -99,8 +103,21 @@ ENDPOINTS = (
REVIEW_RESOURCE_NAME,
EARLY_FRAUD_WARNING_RESOURCE_NAME,
SHIPPING_RATE_RESOURCE_NAME,
+ OUTBOUND_PAYMENT_RESOURCE_NAME,
+ PAYOUT_INTENT_RESOURCE_NAME,
+ RECEIVED_CREDIT_RESOURCE_NAME,
+ INBOUND_TRANSFER_RESOURCE_NAME,
)
+# API v2 list paths. These tables exist only on STRIPE_V2_MONEY_MANAGEMENT_VERSIONS; the v1 tables
+# stay on their v1 lists under every version.
+V2_LIST_PATHS: dict[str, str] = {
+ OUTBOUND_PAYMENT_RESOURCE_NAME: "/v2/money_management/outbound_payments",
+ PAYOUT_INTENT_RESOURCE_NAME: "/v2/money_management/payout_intents",
+ RECEIVED_CREDIT_RESOURCE_NAME: "/v2/money_management/received_credits",
+ INBOUND_TRANSFER_RESOURCE_NAME: "/v2/money_management/inbound_transfers",
+}
+
INCREMENTAL_ENDPOINTS = (
ACCOUNT_RESOURCE_NAME,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/source.py
index 52b0e4965eb4..6de2094ae389 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/source.py
@@ -50,12 +50,15 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.con
RESOURCE_TO_STRIPE_OBJECT_TYPE,
RESOURCE_TO_STRIPE_WEBHOOK_EVENT,
STRIPE_API_VERSION_ACACIA,
+ STRIPE_API_VERSION_ENDIVE,
+ STRIPE_V2_MONEY_MANAGEMENT_VERSIONS,
SUBSCRIPTION_RESOURCE_NAME,
)
from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.settings import (
APPEND_ONLY_INCREMENTAL_FIELDS as STRIPE_APPEND_ONLY_INCREMENTAL_FIELDS,
DEFAULT_OFF_ENDPOINTS as STRIPE_DEFAULT_OFF_ENDPOINTS,
ENDPOINTS as STRIPE_ENDPOINTS,
+ V2_LIST_PATHS as STRIPE_V2_LIST_PATHS,
WAREHOUSE_PARENT_FANOUT,
WEBHOOK_ONLY_ENDPOINTS as STRIPE_WEBHOOK_ONLY_ENDPOINTS,
WEBHOOK_SYNC_ONLY_ENDPOINTS as STRIPE_WEBHOOK_SYNC_ONLY_ENDPOINTS,
@@ -224,8 +227,8 @@ class StripeSource(
lists_tables_without_credentials = True # static endpoint catalog — safe for public docs
has_managed_hogql_schema = True # canonical Stripe schema in external_table_definitions
- supported_versions = (STRIPE_API_VERSION_ACACIA,)
- default_version = STRIPE_API_VERSION_ACACIA
+ supported_versions = (STRIPE_API_VERSION_ACACIA, STRIPE_API_VERSION_ENDIVE)
+ default_version = STRIPE_API_VERSION_ENDIVE
api_docs_url = "https://docs.stripe.com/changelog"
@property
@@ -434,6 +437,9 @@ If automatic creation failed with a permissions error, the fix depends on how yo
"Integration not found": "The linked Stripe integration no longer exists. Please reconnect your Stripe account.",
"Stripe access token not found": "Stripe OAuth access token is missing. Please reconnect your Stripe account.",
"Your Stripe OAuth connection has expired or been revoked. Please reconnect your Stripe account.": "Your Stripe OAuth connection has expired or been revoked. Please reconnect your Stripe account.",
+ # A table that only newer API versions serve, synced under an older pinned version.
+ # The message names the versions that serve it.
+ "is not available on Stripe API version": None,
# Stripe's own `invalid_request_error` body with no usable detail, seen when listing a
# specific customer's nested resources (e.g. payment methods). It is a 400-class error,
# so retrying replays the identical request against the same customer and fails
@@ -505,6 +511,7 @@ If automatic creation failed with a permissions error, the fix depends on how yo
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
+ serves_v2_lists = self.resolve_api_version(api_version) in STRIPE_V2_MONEY_MANAGEMENT_VERSIONS
schemas = [
SourceSchema(
name=endpoint,
@@ -532,6 +539,7 @@ If automatic creation failed with a permissions error, the fix depends on how yo
should_sync_default=endpoint not in STRIPE_DEFAULT_OFF_ENDPOINTS,
)
for endpoint in STRIPE_ENDPOINTS
+ if serves_v2_lists or endpoint not in STRIPE_V2_LIST_PATHS
]
if names is not None:
names_set = set(names)
@@ -549,7 +557,12 @@ If automatic creation failed with a permissions error, the fix depends on how yo
endpoints = [schema_name] if schema_name is not None else None
try:
api_key = self._get_api_key(config, team_id)
- if validate_stripe_credentials(api_key, endpoints, auth_method=config.auth_method.selection):
+ if validate_stripe_credentials(
+ api_key,
+ endpoints,
+ auth_method=config.auth_method.selection,
+ api_version=self.resolve_api_version(api_version),
+ ):
return True, None
else:
return False, "Invalid Stripe credentials"
@@ -624,7 +637,12 @@ If automatic creation failed with a permissions error, the fix depends on how yo
return dict.fromkeys(endpoints, "Stripe credentials are not available")
try:
- return check_stripe_endpoint_permissions(api_key, endpoints, auth_method=config.auth_method.selection)
+ return check_stripe_endpoint_permissions(
+ api_key,
+ endpoints,
+ auth_method=config.auth_method.selection,
+ api_version=self.resolve_api_version(api_version),
+ )
except StripeAuthenticationError as e:
return dict.fromkeys(endpoints, e.stripe_message)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/stripe.py b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/stripe.py
index 332aa0810168..215344359dae 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/stripe.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/stripe.py
@@ -7,6 +7,7 @@ import dataclasses
from collections.abc import Callable, Generator, Iterable, Iterator, Mapping
from datetime import UTC, datetime
from typing import TYPE_CHECKING, Any, Literal, Optional, Union, cast, get_args, get_type_hints
+from urllib.parse import urlsplit
import orjson
import stripe as stripe_lib
@@ -84,6 +85,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.con
SETUP_ATTEMPT_RESOURCE_NAME,
SETUP_INTENT_RESOURCE_NAME,
SHIPPING_RATE_RESOURCE_NAME,
+ STRIPE_V2_MONEY_MANAGEMENT_VERSIONS,
SUBSCRIPTION_ITEM_RESOURCE_NAME,
SUBSCRIPTION_RESOURCE_NAME,
SUBSCRIPTION_SCHEDULE_RESOURCE_NAME,
@@ -106,6 +108,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.set
DEFAULT_PRIMARY_KEYS,
NON_PARTITIONED_ENDPOINTS,
PRIMARY_KEYS,
+ V2_LIST_PATHS,
WAREHOUSE_PARENT_FANOUT,
WEBHOOK_ONLY_ENDPOINTS,
)
@@ -218,6 +221,16 @@ def _is_truncated_stripe_list_response(body: Any) -> bool:
return _head_mentions_list_object(raw, start)
+def _is_truncated_json_object(body: Any) -> bool:
+ """True when ``body`` opens a JSON object but never closes it. API v2 lists carry no
+ ``"object": "list"`` marker, so this is the only shape check that applies to them."""
+ bounds = _trimmed_body_bounds(body)
+ if bounds is None:
+ return False
+ raw, start, end = bounds
+ return raw[start] == _OPEN_BRACE and raw[end] != _CLOSE_BRACE
+
+
def _is_non_list_stripe_response(body: Any) -> bool:
"""True when ``body`` is a *complete* JSON object that is not a Stripe ``list``.
@@ -272,6 +285,7 @@ class _RateLimitRetryingRequestsClient(RequestsClient):
# Records the method of the in-flight request so `_should_retry` (whose signature omits it) can
# scope the non-list-body retry to reads, never a single-object write response.
_last_request_method: str = ""
+ _last_request_is_v2: bool = False
def __init__(
self,
@@ -295,6 +309,7 @@ class _RateLimitRetryingRequestsClient(RequestsClient):
post_data: Any = None,
) -> tuple[bytes, int, Mapping[str, str]]:
self._last_request_method = (method or "").lower()
+ self._last_request_is_v2 = urlsplit(url).path.startswith("/v2/")
if self._before_request is not None:
self._before_request()
return super().request(method, url, headers, post_data)
@@ -329,6 +344,8 @@ class _RateLimitRetryingRequestsClient(RequestsClient):
body, status_code, _ = response
if not (200 <= status_code < 300):
return False
+ if self._last_request_is_v2:
+ return self._last_request_method == "get" and _is_truncated_json_object(body)
if _is_truncated_stripe_list_response(body):
return True
# A complete but non-list body identifies a corrupt list read only for a GET — a write
@@ -477,6 +494,39 @@ class _SingleObjectList:
yield self._obj
+class _V2ListPage:
+ """A fetched API v2 list page behind the ``auto_paging_iter`` interface of the v1 lists.
+
+ API v2 pages by following `next_page_url`, not by object-id cursors, so the first page is
+ requested up front (a probe surfaces its error there) and later pages are fetched lazily.
+ """
+
+ def __init__(self, client: StripeClient, page: dict[str, Any]) -> None:
+ self._client = client
+ self._page = page
+
+ def auto_paging_iter(self) -> Iterator[dict[str, Any]]:
+ page = self._page
+ while True:
+ data = page.get("data")
+ # A page without `data` is a corrupt response, not the end of the list. Raise so the sync
+ # retries rather than finishing with a truncated table.
+ if not isinstance(data, list):
+ raise stripe_lib.APIError("Stripe returned an API v2 list page without a data array")
+ yield from data
+ next_page_url = page.get("next_page_url")
+ if not next_page_url:
+ return
+ page = self._client.raw_request("get", next_page_url).data
+
+
+def _v2_lister(client: StripeClient, path: str) -> Callable[..., ListObject[Any]]:
+ def _list(params: dict[str, Any]) -> ListObject[Any]:
+ return cast(ListObject[Any], _V2ListPage(client, client.raw_request("get", path, limit=params["limit"]).data))
+
+ return _list
+
+
def _credit_balance_summary_lister(client: StripeClient) -> Callable[..., ListObject[Any]]:
"""`/v1/billing/credit_balance_summary` is a retrieve, not a list: it returns the balance for one
customer under a required `filter`. We scope it to a single credit grant so each row is the
@@ -942,6 +992,7 @@ def _build_resources(
parent=StripeResource(method=client.setup_intents.list),
parent_name=SETUP_INTENT_RESOURCE_NAME,
),
+ **{name: StripeResource(method=_v2_lister(client, path)) for name, path in V2_LIST_PATHS.items()},
}
@@ -1011,10 +1062,21 @@ def get_rows(
logger.debug(f"Stripe: {endpoint} endpoint is webhook-only, skipping API list")
return
+ if endpoint in V2_LIST_PATHS and api_version not in STRIPE_V2_MONEY_MANAGEMENT_VERSIONS:
+ raise StripeUnsupportedVersionError(endpoint, api_version)
+
resource = resources.get(endpoint, None)
if not resource:
raise Exception(f"Stripe endpoint does not exist: {endpoint}")
+ if endpoint in V2_LIST_PATHS:
+ # A v2 page token cannot be saved as a v1 `starting_after` cursor, so these full-refresh tables
+ # save no resume state. An interrupted sync reads the list again and overwrites the table.
+ yield from _batch_and_yield(
+ _iter_cleaning_errors(_call_stripe(resource.method, params=default_params).auto_paging_iter()), batcher
+ )
+ return
+
logger.debug(f"Stripe: reading from resource {resource}")
incremental_field_config = APPEND_ONLY_INCREMENTAL_FIELDS.get(endpoint, [])
@@ -1721,6 +1783,16 @@ class StripeTransientError(Exception):
super().__init__(stripe_message)
+class StripeUnsupportedVersionError(Exception):
+ """A table was synced under a pinned API version that does not serve its endpoint."""
+
+ def __init__(self, endpoint: str, api_version: str):
+ super().__init__(
+ f"Stripe {endpoint} is not available on Stripe API version {api_version}. "
+ f"It needs one of: {', '.join(STRIPE_V2_MONEY_MANAGEMENT_VERSIONS)}."
+ )
+
+
class StripeValidationError(Exception):
"""Raised when one or more resources failed with a non-403, non-transient exception (e.g. an
unexpected response or schema error) during credential validation. Transient Stripe-side
@@ -1780,13 +1852,19 @@ def validate_credentials(
api_key: str,
endpoints: Optional[list[str]] = None,
auth_method: Literal["api_key", "oauth"] = "api_key",
+ api_version: Optional[str] = None,
) -> bool:
"""Validate Stripe credentials.
- ``endpoints=None``: single auth probe. 401 → ``StripeAuthenticationError``, 403 → pass.
- ``endpoints=[...]``: probe each (nested → parent). Raises Permission/Validation errors.
"""
- client = StripeClient(api_key, base_addresses=_stripe_base_addresses(), http_client=_tracked_stripe_http_client())
+ client = StripeClient(
+ api_key,
+ stripe_version=api_version,
+ base_addresses=_stripe_base_addresses(),
+ http_client=_tracked_stripe_http_client(),
+ )
all_resources = _build_resources(client, logger=None)
if endpoints is None:
@@ -1834,12 +1912,18 @@ def check_endpoint_permissions(
api_key: str,
endpoints: list[str],
auth_method: Literal["api_key", "oauth"] = "api_key",
+ api_version: Optional[str] = None,
) -> dict[str, str | None]:
"""Probe each endpoint's read scope. Returns ``{name: None}`` if reachable, ``{name: reason}`` otherwise.
Never raises for missing permissions (schema UI needs the full picture). 401 still raises.
"""
- client = StripeClient(api_key, base_addresses=_stripe_base_addresses(), http_client=_tracked_stripe_http_client())
+ client = StripeClient(
+ api_key,
+ stripe_version=api_version,
+ base_addresses=_stripe_base_addresses(),
+ http_client=_tracked_stripe_http_client(),
+ )
all_resources = _build_resources(client, logger=None)
results: dict[str, str | None] = {}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/tests/test_stripe_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/tests/test_stripe_source.py
index edf6f7a4f1f5..c64f1fca8171 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/tests/test_stripe_source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/stripe/tests/test_stripe_source.py
@@ -72,6 +72,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.con
INVOICE_ITEM_RESOURCE_NAME,
INVOICE_PAYMENT_RESOURCE_NAME,
INVOICE_RESOURCE_NAME,
+ OUTBOUND_PAYMENT_RESOURCE_NAME,
PAYMENT_INTENT_RESOURCE_NAME,
PAYMENT_LINK_RESOURCE_NAME,
PAYMENT_METHOD_HISTORY_MAPPING_KEY,
@@ -86,6 +87,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.con
SETUP_INTENT_RESOURCE_NAME,
SHIPPING_RATE_RESOURCE_NAME,
STRIPE_API_VERSION_ACACIA,
+ STRIPE_API_VERSION_ENDIVE,
SUBSCRIPTION_ITEM_RESOURCE_NAME,
SUBSCRIPTION_RESOURCE_NAME,
SUBSCRIPTION_SCHEDULE_RESOURCE_NAME,
@@ -112,6 +114,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.stripe.str
StripeNestedResource,
StripeResource,
StripeTransientError,
+ StripeUnsupportedVersionError,
StripeValidationError,
_all_known_webhook_events,
_coerce_incremental_cursor,
@@ -303,6 +306,98 @@ def _stripe_list_api(objects: list[dict[str, Any]], field: str) -> Callable[[Rec
return respond
+def _v2_list_api(pages: dict[str | None, dict[str, Any]]) -> Callable[[RecordedRequest], ScriptedResponse]:
+ def respond(request: RecordedRequest) -> ScriptedResponse:
+ return ScriptedResponse(json=pages[request.param("page")])
+
+ return respond
+
+
+class TestStripeApiVersionDispatch:
+ def _driver(self) -> SourceDriver:
+ return SourceDriver(
+ StripeSource(),
+ StripeSourceConfig(auth_method=StripeAuthMethodConfig(selection="api_key", stripe_secret_key="sk_test")),
+ )
+
+ @parameterized.expand(
+ [
+ ("acacia_pin", STRIPE_API_VERSION_ACACIA, STRIPE_API_VERSION_ACACIA),
+ ("endive_pin", STRIPE_API_VERSION_ENDIVE, STRIPE_API_VERSION_ENDIVE),
+ ("unpinned_takes_default", None, STRIPE_API_VERSION_ENDIVE),
+ ]
+ )
+ def test_v1_list_sends_the_resolved_version(self, _name, pin, expected_header):
+ result = self._driver().run(
+ CHARGE_RESOURCE_NAME, _stripe_list_api([{"id": "ch_1", "created": NOW}], "created"), api_version=pin
+ )
+
+ assert result.raised is None
+ assert result.paths == ["/v1/charges"]
+ assert {request.headers["stripe-version"] for request in result.requests} == {expected_header}
+
+ def test_v2_list_follows_next_page_url_under_endive(self):
+ path = "/v2/money_management/outbound_payments"
+ pages: dict[str | None, dict[str, Any]] = {
+ None: {
+ "data": [{"id": "obp_2", "created": "2026-10-29T10:00:00.000Z"}],
+ "next_page_url": f"{path}?page=tok_2",
+ "previous_page_url": None,
+ },
+ "tok_2": {
+ "data": [{"id": "obp_1", "created": "2026-10-28T10:00:00.000Z"}],
+ "next_page_url": None,
+ "previous_page_url": f"{path}?page=tok_1",
+ },
+ }
+
+ with mock.patch.object(stripe_module, "STRIPE_CHUNK_SIZE", 1):
+ result = self._driver().run(
+ OUTBOUND_PAYMENT_RESOURCE_NAME, _v2_list_api(pages), api_version=STRIPE_API_VERSION_ENDIVE
+ )
+
+ assert result.raised is None
+ assert [row["id"] for table in result.rows for row in table.to_pylist()] == ["obp_2", "obp_1"]
+ assert result.paths == [path, path]
+ assert {request.headers["stripe-version"] for request in result.requests} == {STRIPE_API_VERSION_ENDIVE}
+ # A saved cursor would mark the next attempt as resumed, and a resumed full refresh appends.
+ assert result.saved_states == []
+
+ def test_v2_page_without_data_fails_instead_of_ending_the_list(self):
+ pages: dict[str | None, dict[str, Any]] = {
+ None: {"data": [{"id": "obp_2"}], "next_page_url": "/v2/money_management/outbound_payments?page=tok_2"},
+ "tok_2": {},
+ }
+
+ result = self._driver().run(
+ OUTBOUND_PAYMENT_RESOURCE_NAME, _v2_list_api(pages), api_version=STRIPE_API_VERSION_ENDIVE
+ )
+
+ assert isinstance(result.raised, stripe_lib.APIError)
+
+ def test_v2_table_under_acacia_pin_fails_without_a_request(self):
+ result = self._driver().run(
+ OUTBOUND_PAYMENT_RESOURCE_NAME, _v2_list_api({}), api_version=STRIPE_API_VERSION_ACACIA
+ )
+
+ assert isinstance(result.raised, StripeUnsupportedVersionError)
+ assert result.requests == []
+
+ @parameterized.expand(
+ [
+ ("acacia", STRIPE_API_VERSION_ACACIA, False),
+ ("endive", STRIPE_API_VERSION_ENDIVE, True),
+ ("unpinned", None, True),
+ ]
+ )
+ def test_discovery_lists_v2_tables_only_where_the_pin_serves_them(self, _name, pin, listed):
+ config = StripeSourceConfig(auth_method=StripeAuthMethodConfig(selection="api_key", stripe_secret_key="sk"))
+ names = {schema.name for schema in StripeSource().get_schemas(config, team_id=1, api_version=pin)}
+
+ assert (OUTBOUND_PAYMENT_RESOURCE_NAME in names) is listed
+ assert CHARGE_RESOURCE_NAME in names
+
+
class TestStripeLatestObjectsOldestFirst:
def _sync(self, resource: str, objects: list[dict[str, Any]], field: str, watermark: int) -> DriveResult:
result = SourceDriver(
diff --git a/products/warehouse_sources/backend/tests/api/test_external_data_source.py b/products/warehouse_sources/backend/tests/api/test_external_data_source.py
index 2788dbdf05a6..d55c99a31733 100644
--- a/products/warehouse_sources/backend/tests/api/test_external_data_source.py
+++ b/products/warehouse_sources/backend/tests/api/test_external_data_source.py
@@ -446,7 +446,7 @@ class TestExternalDataSource(APIBaseTest):
# new sources are pinned to the source type's default vendor API version at creation,
# so a later default flip never changes their sync behavior
source = ExternalDataSource.objects.get(id=payload["id"])
- self.assertEqual(source.api_version, "2024-09-30.acacia")
+ self.assertEqual(source.api_version, "2026-10-28.endive")
@patch(
"products.warehouse_sources.backend.temporal.data_imports.sources.stripe.source.StripeSource.validate_credentials",
diff --git a/products/warehouse_sources/backend/tests/api/test_public_source_configs.py b/products/warehouse_sources/backend/tests/api/test_public_source_configs.py
index a96f03116486..d1b1b82da11f 100644
--- a/products/warehouse_sources/backend/tests/api/test_public_source_configs.py
+++ b/products/warehouse_sources/backend/tests/api/test_public_source_configs.py
@@ -114,8 +114,8 @@ class TestPublicSourceConfigs(APIBaseTest):
assert isinstance(config["deprecatedVersions"], list), source_type
stripe = data["Stripe"]
- assert stripe["versions"] == ["2024-09-30.acacia"]
- assert stripe["defaultVersion"] == "2024-09-30.acacia"
+ assert stripe["versions"] == ["2024-09-30.acacia", "2026-10-28.endive"]
+ assert stripe["defaultVersion"] == "2026-10-28.endive"
assert stripe["apiDocsUrl"] == "https://docs.stripe.com/changelog"
def test_many_fixed_schema_sources_list_tables(self):
diff --git a/products/warehouse_sources/backend/tests/management/test_repin_stripe_webhook_api_version.py b/products/warehouse_sources/backend/tests/management/test_repin_stripe_webhook_api_version.py
index 1e7d5176025d..b1f70505a650 100644
--- a/products/warehouse_sources/backend/tests/management/test_repin_stripe_webhook_api_version.py
+++ b/products/warehouse_sources/backend/tests/management/test_repin_stripe_webhook_api_version.py
@@ -39,6 +39,7 @@ def _create_source_with_webhook(
connection_id=str(uuid.uuid4()),
source_type="Stripe",
job_inputs={"stripe_secret_key": secret_key, "auth_method": auth_method},
+ api_version=STRIPE_API_VERSION_ACACIA,
)
hog_function = HogFunction.objects.create(
team=team,