Marketplace order mapping

Marketplace payloads are ingestion hints, not public contracts. OmniCommerce uses each hint to refresh the authoritative order, then builds the public event from the stored order and line aggregate. This mapping applies to the standardized order events. Product and look events describe OmniCommerce workspace resources; see Product webhooks and Look webhooks for those source boundaries. Finance is a separate lifecycle. A provider order push may trigger a finance refresh, but settlement events are emitted only after authoritative marketplace transactions or escrow detail are normalized and committed.

​

Provider provenance

Provider event names are explicitly allowlisted. Unknown event types are acknowledged or ignored by the adapter and never guessed from substrings. Order identity is scoped by organizationId, marketplace, exact accountId, and external order ID. A missing account is never treated as a wildcard.

​

Status normalization

marketplaceStatus preserves the original provider value. status is the provider-neutral value consumers should use for workflows. These are representative values, not an exhaustive provider enum. New raw provider values can be introduced without changing the public status enum.

​

Partial notifications

Marketplace notifications often contain only an order ID and status. The adapter refreshes the order before publishing so consumers receive totals, currency, timestamps, and the line aggregate from committed OmniCommerce state—not the partial provider body. If the provider redelivers a receipt and the canonical snapshot is unchanged, no new public lifecycle event is created. If a later correction changes public state, OmniCommerce emits a new event with a higher resourceVersion. The same rule applies to finance retries. An unchanged escrow or transaction response creates no duplicate settlement event. A later fee, net, reference, or status correction emits settlement.updated or settlement.status.changed.

​

Deletions and cancellations

Shopify orders/delete produces order.deleted with a minimal tombstone. Marketplace cancellations from any provider remain orders and map to order.status.changed with status=canceled.

​

Consumer boundary

Do not persist or branch on marketplace webhook bodies in the Spresso-facing integration. Persist the unified order snapshot and use source only for provenance, support diagnostics, and receipt correlation. Persist settlement snapshots separately from orders; do not overwrite order totals with seller-wallet values.