commerce is the product-centric analytics boundary of EUSRR. It does not replace an operational CRM or warehouse. External and future internal systems all supply records to the same canonical product model.

Stable model

Product is one sellable or stockable SKU. parent groups variants.
SourceRecord retains the latest raw payload with source provenance.
ProductBinding maps a source product/offer identifier to Product.
Sale and SaleLine contain normalized product-level sales facts.
Cost contains commissions, delivery, advertising and other expenses.
StockSnapshot contains point-in-time stock observations by source and warehouse.

Money is never aggregated across currencies. Returns are represented as a Sale with event_type="return"; line values remain positive and analytics applies the sign.

Integration contract

An adapter subclasses commerce.integrations.SourceAdapter, handles API pagination internally and yields ExternalRecord objects. Register it in adapter_registry, then invoke the Celery task commerce.sync_source.

Adapters must not store credentials in SourceSystem.metadata; secrets belong in environment-backed configuration or a dedicated encrypted credential store.

Source-specific code must not create alternative product models. It stores the raw payload first and then resolves a product through ProductBinding or commerce.services.match_product before writing normalized facts.

API

The authenticated API is mounted at /api/v1/commerce/:

products/
products/{id}/analytics/
sources/
product-bindings/
sales/
sale-lines/
costs/
stock-snapshots/

All employees may read. Writes require staff status or the corresponding Django model permission. The frontend management screen can bootstrap and correct normalized records manually; integrations should still write them through application services so raw provenance and idempotency are preserved.