Source capability and enablement contract¶

No ecommerce connection is enabled from product documentation or connector reputation alone. Accountify captures evidence from the exact tenant connection, connector version, configured catalog, credentials, permissions, source account, and historical range.

Capability state¶

unknown -> scanning -> supported
unknown -> scanning -> unsupported
supported -> degraded | expired | drifted
degraded | expired | drifted -> scanning

Only supported capabilities whose evidence has not expired may satisfy a workflow gate. A workflow is enabled only when every capability in its named profile is supported.

Evidence record¶

create table source_capability_evidence (
  tenant_id uuid not null,
  source_connection_id uuid not null,
  capability text not null,
  status text not null check (status in (
    'unknown','scanning','supported','unsupported','degraded','expired','drifted'
  )),
  connector_name text not null,
  connector_version text not null,
  configured_catalog_sha256 char(64) not null,
  source_account_fingerprint text not null,
  evidence jsonb not null,
  checked_at timestamptz not null,
  expires_at timestamptz not null,
  last_success_at timestamptz,
  failure_code text,
  primary key (tenant_id, source_connection_id, capability)
);

Evidence includes configured stream, sync mode, primary key, cursor, start date, lookback, permission scopes, representative record counts, oldest/newest timestamps, required fields observed, deletion behavior where relevant, and an encrypted reference to the scan output.

Shopify pilot profile¶

The pilot validates the exact Airbyte Shopify connector deployed in the environment. As of July 2, 2026, the official connector documentation reports version 3.5.1, full-refresh and incremental modes, no namespace support, limited deletion capture, and an explicit option for closed fulfillment orders. These facts guide the scan but do not replace tenant evidence. See the official Shopify connector reference.

Capability	Required evidence	Enables
`shopify.orders.read`	Orders stream, stable order/line IDs, update cursor, order currency/tax/discount fields	Canonical orders
`shopify.transactions.read`	Transactions stream, transaction type/status/amount/currency/provider reference	Payment facts
`shopify.refunds.read`	Order Refunds stream and line/transaction relationships	Refund workflow
`shopify.fulfillments.read`	Fulfillments plus closed fulfillment orders enabled and observed	Delivery workflow
`shopify.products.read`	Products, variants, SKU, inventory item references	Product mapping
`shopify.locations.read`	Locations and stable location IDs	Warehouse mapping
`shopify.inventory.read`	Inventory items/levels where inventory reconciliation is enabled	Inventory comparison
`shopify.payments.read`	Balance transactions and payouts for Shopify Payments tenants	Settlement close
`shopify.disputes.read`	Disputes stream and required lifecycle fields	Dispute handling
`shopify.webhooks.orders`	Verified create/update/cancel delivery with unique delivery ID	Freshness path
`shopify.webhooks.refunds`	Verified refund/update coverage	Refund freshness
`shopify.webhooks.fulfillments`	Verified fulfillment coverage	Delivery freshness
`shopify.completeness`	Daily IDs/counts/amount controls and successful bounded backfill	Production enablement

If Shopify Payments is not used, the tenant must activate and validate a separate payment-provider capability profile before payment and payout reconciliation can be enabled.

Required connector configuration¶

OAuth with least-privilege read scopes is preferred for managed Airbyte connections.
start_date covers the approved historical backfill period.
lookback_window_in_days starts at three days and is changed only from observed late-update evidence.
Closed fulfillment orders are included.
Only required streams are selected; unrelated customer/marketing/content streams are disabled.
Connector image/version and catalog hash are pinned in evidence for every run.
Raw destination naming is not trusted as a tenant boundary.

Scan procedure¶

Resolve the active tenant/source binding and retrieve secrets from the secrets manager.
Test authentication and record the granted scopes without storing secret values.
Discover the connector catalog and hash its normalized representation.
Compare required streams, fields, primary keys, cursors, and modes to the profile.
Execute a bounded sample sync and inspect accepted/rejected counts and schema.
Validate IDs, timestamps, currencies, signs, totals, relationships, and late updates against fixtures.
Verify webhook signature, duplicate delivery, ordering, and asynchronous acknowledgement behavior.
Execute a bounded reconciliation read directly from the source API where available.
Store evidence, expiry, adapter version, and stable failure codes.
Recompute the workflow gate and emit source.capability.changed.v1.

Drift and expiry¶

A rescan is required when connector version, configured catalog, source scopes, webhook subscription, source account, adapter version, or required schema changes. Evidence also expires after 30 days for mutation-enabling capabilities and after seven days for settlement-close capabilities.

The following immediately mark affected capabilities drifted or degraded:

unknown required field or enum;
cursor regression or stalled cursor;
selected stream removed or sync mode changed;
repeated missing-ID or amount-control failures;
webhook signature failures or disabled subscriptions;
permission/scopes reduced;
connector upgrade outside the approved version range;
records observed for an unexpected shop/account identity.

Drift disables new posting intents for affected workflows. Already accepted operations continue only when their inputs and Odoo preconditions are unaffected; otherwise they enter blocked.

Additional source admission¶

Amazon, eBay, another shop, or another payment provider is not admitted by adding rows to this table. Each source requires:

a source-specific capability profile and official API/connector references;
source identity, event, cursor, deletion, rate-limit, settlement, and backfill analysis;
canonical adapter fixtures and control equations;
data classification review;
reconciliation and accounting policy approval;
failure-injection and shadow-run evidence;
an architecture decision approving production use.

The Airbyte Amazon Seller Partner connector may be evaluated for a later profile, but its existence is not evidence that Accountify's required order and settlement semantics are complete.

Enablement API¶

GET  /api/v1/operations/tenants/{tenant_id}/source-capabilities
POST /api/v1/operations/tenants/{tenant_id}/source-capability-scans
GET  /api/v1/operations/source-capability-scans/{scan_id}
POST /api/v1/operations/tenants/{tenant_id}/source-profiles/{profile}/enable
POST /api/v1/operations/tenants/{tenant_id}/source-profiles/{profile}/disable

Enable/disable commands require an operations administrator, reason, step-up authentication, audit, and idempotency key. Enablement fails with CAPABILITY_EVIDENCE_MISSING, CAPABILITY_EVIDENCE_EXPIRED, or CAPABILITY_PROFILE_UNSATISFIED rather than partially enabling a workflow.

Acceptance criteria¶

A fixture proves each required Shopify stream and relationship for the deployed connector version.
Missing stream, missing permission, wrong shop identity, stale evidence, schema drift, and failed completeness checks prevent enablement.
A connector upgrade cannot bypass rescan through a cached status.
Capability evidence is tenant-isolated, immutable per scan, and linked to the configured catalog hash.
Disabling a profile prevents new work while preserving evidence and safely classifying in-flight operations.