: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
from typing import Optional, cast
from products.warehouse_sources.sources.bigcommerce._config import BigCommerceSourceConfig
from products.warehouse_sources.sources.bigcommerce.bigcommerce import (
BigCommerceResumeConfig,
bigcommerce_source,
order_fan_out_source,
validate_credentials as validate_bigcommerce_credentials,
)
from products.warehouse_sources.sources.bigcommerce.settings import (
ENDPOINTS,
INCREMENTAL_FIELDS,
ORDER_FAN_OUT_ENDPOINTS,
PARTITION_FIELDS,
PRIMARY_KEYS,
)
from products.warehouse_sources.sources.sdk import (
CanonicalDescriptions,
DataWarehouseSourceCategory,
ExternalDataSourceType,
FieldType,
ReleaseStatus,
ResumableSource,
ResumableSourceManager,
SourceConfig,
SourceFieldInputConfig,
SourceFieldInputConfigType,
SourceInputs,
SourceRegistry,
SourceResponse,
SourceSchema,
build_endpoint_schemas,
detect,
)
@SourceRegistry.register
class BigCommerceSource(ResumableSource[BigCommerceSourceConfig, BigCommerceResumeConfig]):
codebase_detection = detect(
env=("^BIGCOMMERCE_",),
script_hosts=("checkout-sdk.bigcommerce.com",),
npm=(
"node-bigcommerce",
"@bigcommerce/checkout-sdk",
"@bigcommerce/catalyst-client",
"@bigcommerce/stencil-utils",
),
pypi=("bigcommerce",),
composer=("bigcommerce/api",),
rubygems=("bigcommerce",),
)
lists_tables_without_credentials = True # static endpoint catalog — safe for public docs
supported_versions = ("v3",)
default_version = "v3"
api_docs_url = "https://developer.bigcommerce.com/api-reference"
@property
def source_type(self) -> ExternalDataSourceType:
return ExternalDataSourceType.BIGCOMMERCE
def get_non_retryable_errors(self) -> dict[str, str | None]:
return {
"401 Client Error": "BigCommerce authentication failed. Check your store hash and access token.",
"403 Client Error": (
"Your BigCommerce access token does not have the required OAuth scopes for this resource."
),
}
def get_canonical_descriptions(self) -> CanonicalDescriptions:
from products.warehouse_sources.sources.bigcommerce.canonical_descriptions import ( # noqa: PLC0415 -- lazy import keeps this out of the hot registration path
CANONICAL_DESCRIPTIONS,
)
return CANONICAL_DESCRIPTIONS
def get_schemas(
self,
config: BigCommerceSourceConfig,
team_id: int,
with_counts: bool = False,
names: list[str] | None = None,
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)
def validate_credentials(
self,
config: BigCommerceSourceConfig,
team_id: int,
schema_name: Optional[str] = None,
api_version: str | None = None,
) -> tuple[bool, str | None]:
if not config.store_hash or not config.access_token:
return False, "Missing BigCommerce credentials"
status = validate_bigcommerce_credentials(config.store_hash, config.access_token)
if status == 200:
return True, None
# A token scoped to only some resources still passes the create-time probe; per-table
# access is reported separately at sync time via get_non_retryable_errors.
if status == 403 and schema_name is None:
return True, None
if status == 403:
return False, "Your BigCommerce access token does not have the required OAuth scopes for this resource."
if status == 401:
return False, "BigCommerce authentication failed. Check your store hash and access token."
return False, "Could not connect to your BigCommerce store. Please check the store hash."
def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[BigCommerceResumeConfig]:
return ResumableSourceManager[BigCommerceResumeConfig](inputs, BigCommerceResumeConfig)
def source_for_pipeline(
self,
config: BigCommerceSourceConfig,
resumable_source_manager: ResumableSourceManager[BigCommerceResumeConfig],
inputs: SourceInputs,
) -> SourceResponse:
# Only the endpoints that expose a server-side "modified since" filter sync
# incrementally — guard against a stale schema requesting it elsewhere.
use_incremental = inputs.should_use_incremental_field and inputs.schema_name in INCREMENTAL_FIELDS
if inputs.schema_name in ORDER_FAN_OUT_ENDPOINTS:
response = SourceResponse(
name=inputs.schema_name,
items=lambda: order_fan_out_source(
config.store_hash, config.access_token, inputs.schema_name, resumable_source_manager
),
primary_keys=PRIMARY_KEYS[inputs.schema_name],
sort_mode="asc",
)
self._set_partitioning(response, inputs.schema_name)
return response
resource = bigcommerce_source(
store_hash=config.store_hash,
access_token=config.access_token,
endpoint=inputs.schema_name,
team_id=inputs.team_id,
job_id=inputs.job_id,
resumable_source_manager=resumable_source_manager,
should_use_incremental_field=use_incremental,
db_incremental_field_last_value=inputs.db_incremental_field_last_value if use_incremental else None,
)
response = SourceResponse(
name=resource.name,
items=lambda: resource,
primary_keys=PRIMARY_KEYS.get(inputs.schema_name, ["id"]),
column_hints=resource.column_hints,
# Whether BigCommerce's `sort`/`direction` params hold a stable ascending order
# page-to-page isn't verified against a live store. Deferring the watermark commit
# until the whole resource has been read (desc semantics) avoids skipping rows if
# the true order turns out not to be strictly ascending.
sort_mode="desc" if use_incremental else "asc",
)
self._set_partitioning(response, inputs.schema_name)
return response
@staticmethod
def _set_partitioning(response: SourceResponse, schema_name: str) -> None:
partition_key = PARTITION_FIELDS.get(schema_name)
if partition_key:
response.partition_count = 1
response.partition_size = 1
response.partition_mode = "datetime"
response.partition_format = "month"
response.partition_keys = [partition_key]
@property
def get_source_config(self) -> SourceConfig:
return SourceConfig(
name=ExternalDataSourceType.BIGCOMMERCE,
category=DataWarehouseSourceCategory.E_COMMERCE,
label="BigCommerce",
caption=(
"Enter your BigCommerce store hash and API access token to pull your store data into "
"the PostHog Data warehouse. Create an API account under **Settings → API → "
"Store-level API accounts** with `read-only` scope for **Products**, **Orders** and "
"**Customers**. To sync channels and order transactions, also grant `read-only` scope for "
"**Channel Settings** and **Order Transactions**."
),
iconPath="/static/services/bigcommerce.png",
docsUrl="https://posthog.com/docs/cdp/sources/bigcommerce",
releaseStatus=ReleaseStatus.GA,
fields=cast(
list[FieldType],
[
SourceFieldInputConfig(
name="store_hash",
label="Store hash",
type=SourceFieldInputConfigType.TEXT,
required=True,
placeholder="abc123",
secret=False,
caption="Found in your store's control panel URL: `https://store-{store_hash}.mybigcommerce.com`.",
),
SourceFieldInputConfig(
name="access_token",
label="Access token",
type=SourceFieldInputConfigType.PASSWORD,
required=True,
placeholder="",
secret=True,
),
],
),
)