Ecommerce ingestion implementation baseline¶

Attribute	Value
Document version	`0.3.0`
Replaces	`0.2.0`
Status	Draft for pilot implementation
Last updated	July 2, 2026
Pilot source	Shopify
Pilot ledger	One client Odoo 19 Online database per tenant
Pilot posting profile	`order_invoice_v1`
Related platform contract	Accountify platform specification
Normative ecommerce contract	Ecommerce accounting architecture
Complete contract set	Ecommerce contract registry

This page replaces the original PR assessment. The assessment established a useful direction but mixed repository commentary, future options, and implementation requirements. The implementation contract now lives in the linked ecommerce pages.

Adopted decisions¶

Airbyte is a replication and backfill component. It does not decide accounting treatment and does not call Odoo.
Shopify webhooks provide the freshness path. Airbyte incremental syncs provide completeness checks, replay, and backfill. Both paths converge through one idempotent ingestion inbox.
Accountify owns source normalization, tenant mappings, policy evaluation, operations, exceptions, and audit evidence.
Client Odoo remains authoritative for posted invoices, credit notes, payments, reconciliations, stock operations, and legal accounting state.
Orders, payments, fulfillments, refunds, returns, disputes, settlements, and payouts have separate state machines. A single linear order status is not sufficient.
The pilot uses order_invoice_v1: one source order maps to one Odoo sale order; Odoo invoices are created from delivered quantities; refunds and returns are separate operations.
Settlement-to-bank reconciliation is a core workflow. An order import is not financially complete until payments, refunds, fees, payouts, and bank evidence reconcile or enter an exception state.
Money is stored as decimal values with an ISO 4217 currency. Binary floating-point is prohibited for accounting decisions.
Every source, canonical, operation, mapping, and reconciliation row is tenant-scoped and protected by the platform's composite tenant keys and forced row-level security.
Success after an Odoo mutation requires authoritative readback. A successful HTTP response alone is not completion evidence.

Pilot boundary¶

The first production slice supports:

Shopify orders, lines, discounts, shipping, tax lines, transactions, refunds, fulfillments, inventory references, Shopify Payments balance transactions, payouts, and disputes where the connector exposes them.
EUR-denominated, single-company Odoo tenants using validated sales, tax, receivable, payment, fee, and stock mappings.
order_invoice_v1 only. Summary posting is a separate future profile and must not share idempotency keys or mapping semantics with order-level posting.
Odoo sale order creation, confirmation, native delivery processing, invoice creation, invoice posting, credit notes, payment registration, and reconciliation through allowlisted commands.
Human exception handling for missing mappings, tax ambiguity, closed periods, currency mismatch, settlement imbalance, chargebacks, and timeout-unknown operations.

The pilot does not support Amazon/eBay, multi-currency settlement netting, gift-card liability, marketplace deemed-supplier tax, OSS/IOSS automation, bundled products, landed cost allocation, or automated inventory adjustments. These cases fail closed with stable error codes.

Required implementation documents¶

Contract	Purpose
Contract registry	Complete pilot contract set, ownership, precedence, artifacts, and readiness boundary
Architecture and scope	Ownership, runtime components, pilot boundary, and delivery sequence
Source capabilities	Connector/stream evidence, drift detection, and enablement gates
Source ingestion	Airbyte, webhooks, tenant attribution, deduplication, freshness, and replay
Canonical commerce model	Durable entities, event envelope, identities, and independent state machines
Mappings and master data	Effective-dated mapping lifecycle, precedence, approval, evidence, and drift
Accounting policy	Posting grain, tax, currency, rounding, dates, journals, and approval gates
API and events	HTTP resources, commands, events, errors, idempotency, and compatibility
Settlements and payouts	Financial equation, matching, bank reconciliation, exceptions, and close
Odoo posting	Approved Odoo surface, commands, mappings, idempotency, and readback
Refunds, returns, and inventory	Financial and physical reversal contracts plus inventory authority
Warehouse marts and reporting	Fact/dimension grains, metric definitions, refresh, reconciliation, and reporting API
Post-Odoo implementation artifacts	Executable readback, outbox, warehouse facts, initial marts, reporting contracts, controls, and monitoring baseline
Data governance	Classification, minimization, access, retention, deletion, exports, and offboarding
Operations and acceptance	Jobs, SLOs, security, observability, tests, rollout, and go-live gates
Operational runbooks	Safe incident containment, diagnosis, recovery, evidence, and exit criteria

Business sign-offs required before production¶

The technical implementation may begin against the pilot defaults. Production posting remains blocked until the accounting owner approves:

invoice timing and tax-point rules per tenant and country;
B2C invoice/receipt obligations and invoice-number handling;
sales-tax/VAT, shipping, discount, gift-card, fee, and rounding mappings;
payment clearing and marketplace clearing account design;
chargeback, reserve, withheld-tax, and foreign-exchange treatment;
stock valuation ownership and the supported fulfillment model;
retention periods for customer, payment, and source payload data.

Approval is versioned as a tenant_posting_policy record. Workers reject work when the policy version is missing, expired, or different from the version captured by the operation.

Definition of implementation-ready¶

The post-Odoo readback-to-reporting slice now has executable pilot reference artifacts. The complete ecommerce implementation is ready for production engineering only when:

all domain database migrations implement the normative keys and constraints and pass runtime migration tests;
the reporting OpenAPI and post-Odoo event schemas are extended with the remaining source, command, and event contracts and pass producer/consumer tests;
the Shopify source capability fixture is verified against a pilot store;
Odoo model, method, access, company, tax, journal, warehouse, and wrapper capabilities pass on a representative Odoo Online clone;
golden fixtures cover order, partial fulfillment, refund without return, return without refund, dispute, payout, and correction scenarios;
security tests prove tenant isolation across PostgreSQL, queues, object storage, logs, exports, and caches;
the accounting owner signs the pilot posting policy and reconciliation tolerances;
all acceptance tests in Operations and acceptance pass.
required runbooks pass tabletop/failure-injection exercises and all marts pass lineage and control-total tests.

Superseded recommendations¶

The following ideas from the original assessment are explicitly rejected or deferred:

Airbyte is not the low-latency event backbone and does not provide exactly-once business events.
A schema-per-source layout is not a tenant boundary. Trusted tenant and source-connection identity is stamped by the control plane on every landed record.
The platform does not advance an order through one combined lifecycle.
Raw payload retention is not unlimited. Payloads are classified, encrypted, access-controlled, and deleted under an approved retention schedule.
Warehouse or orchestration migrations are triggered by measured volume, concurrency, recovery, retention, SLO, and cost limits, not a client-count threshold alone.
Repository PR statistics and temporary review status do not belong in an architecture contract.