Marketplace inventory sync with one stock authority
Translate warehouse truth into channel-specific sellable quantities, reserve orders once, process every change idempotently, and reconcile remote offers before stale stock becomes an oversale.
Assign ownership before connecting APIs
Overselling begins when several systems believe they own the same fact. Write a field-level authority matrix for physical stock, reservations, allocations, listings, orders, fulfillment, and returns.
Physical stock
Usually owned by the WMS or fulfillment system per item, condition, lot where relevant, and physical location.
Operational availability
Derived from physical stock after committed, reserved, damaged, quality-control, safety-stock, and other unavailable states.
Cross-channel allocation
Owned by the OMS or connector policy that decides how shared sellable stock is exposed across channels and buffers.
Marketplace offer
Published by the connector and accepted or rejected by the marketplace. Remote accepted state must be observed as its own fact.
Order reservation
Created exactly once in the authoritative ledger when an eligible order is accepted; cancellations and returns reverse it through explicit events.
Fulfillment state
Owned by the warehouse or fulfillment provider, then translated into channel shipment, cancellation, and return operations.
Merchant-specific availability policy
channel offer = maximum of zero and the eligible on-hand stock minus committed units, internal reservations, quality holds, safety stock, and quantities allocated elsewhere
This is a policy shape, not a universal accounting formula. Define whether inbound, backorder, dropship, transfer, preorder, and marketplace-fulfilled stock can contribute for each channel, location, service level, and product class.
Translate platform models; do not flatten them
The canonical model must preserve the distinctions needed to calculate a channel promise and explain discrepancies. A single quantity column loses information that the platforms themselves retain.
| Platform | Important objects and states | Connector consequence |
|---|---|---|
| Amazon | Seller-provided SKU and listing quantity for merchant fulfillment; separate FBA fulfillable, reserved, inbound, unfulfillable, and other availability states | Keep merchant-fulfilled offers separate from marketplace-managed stock. Consume order and quantity notifications, then reconcile because some inventory events are periodic or delayed. |
| eBay | Seller SKU, inventory item, merchant location, offer, marketplace, business policies, and item groups for variations | Map product identity separately from marketplace offers and locations. Preserve offer and listing identifiers; API-managed listings can carry editing restrictions outside the API. |
| Shopify | Product variant, inventory item, inventory level per location, and states including on-hand, available, committed, reserved, damaged, safety stock, quality control, and incoming | Do not overwrite platform-managed committed quantities. Use the correct set, adjust, move, activation, or order operation and preserve the adjustment cause. |
| WMS or ERP | Item, warehouse, bin, condition, lot or serial where used, on-hand, allocations, picks, transfers, receipts, returns, and adjustments | Define which level is authoritative and what can be exposed. Marketplace APIs often cannot represent the full warehouse state, so publish a derived quantity with traceable inputs. |
Amazon evidence
SP-API documents event-driven listing and inventory notifications, including merchant-fulfilled quantity changes and FBA availability. Notification types.
eBay evidence
eBay's official model separates locations, inventory items, offers, marketplaces, policies, and variation groups. Inventory API overview.
Shopify evidence
Shopify documents multiple inventory states and reserves control of committed quantities for order and fulfillment actions. Inventory model.
SKU mapping is a governed identity ledger
A visible SKU string is not a reliable global key. Preserve each platform's stable identifiers and the effective-dated mapping between merchant products, variants, warehouse items, listings, offers, and locations.
Canonical product
Merchant product and variant identifiers, barcode where trustworthy, pack size, unit, bundle definition, status, and owner.
Channel identity
Account, region or marketplace, seller SKU, catalog identifier, listing or offer ID, variation group, fulfillment channel, and publication state.
Location identity
Warehouse and channel location IDs, fulfillment eligibility, service area, lead time, priority, aggregation rule, and activation state.
Mapping lifecycle
Effective time, source, approval, confidence, replacement history, split or merge rule, duplicate detection, and the events that require re-publication.
Bundle graph
Parent offer, component item, quantity per bundle, substitutes, virtual or prebuilt status, location applicability, and reservation behavior.
Quarantine
Unknown SKU, ambiguous match, missing location, invalid variation, duplicate identity, and retired mapping must stop safely in an owned exception queue.
An event-driven path with snapshot reconciliation
Events keep offers fresh; scheduled snapshots prove convergence. Both paths use the same canonical identities, policy, idempotency, and exception ledger.
Ingress adapters
Receive signed webhooks, marketplace notifications, WMS changes, order events, and scheduled snapshots. Persist the raw envelope before acknowledging where possible.
Inbox and deduplication
Key events by source, account, event ID or deterministic fingerprint; retain ordering metadata, delivery attempts, payload version, and processing result.
Canonical ledger
Resolve product and location identity, apply stock-state transitions, create reservations exactly once, record cause and version, and reject stale or invalid transitions.
Allocation policy
Calculate each channel offer from eligible stock, reservations, buffers, bundle constraints, location rules, fulfillment mode, and merchant-approved backorder policy.
Outbox and adapters
Queue desired channel state transactionally, coalesce superseded quantities safely, respect API-specific mutation semantics, retry policy, limits, and idempotency support.
Observation and reconciliation
Capture accepted state, warnings, listing issues, and remote snapshots; compare desired versus observed state and open owned discrepancies with repair actions.
Idempotent stock change
operation key + canonical item and location + cause reference + expected prior version or quantity + requested change + resulting observed state + immutable processing record
Shopify documents both idempotency and compare-and-swap support for inventory adjustments, plus a reference URI for adjustment traceability. Use native safeguards where available and preserve equivalent controls in the connector ledger. Shopify quantity guidance.
Why reconciliation remains mandatory
Acknowledgement means the API received a request, not that the listing stayed buyable or that later orders, cancellations, manual edits, policy changes, and delayed events preserved the intended quantity. Periodically read remote truth and compare it to the latest desired state.
Failure handling must protect stock before throughput
Define the safe degraded behavior for each failure. Retrying every request immediately can amplify throttling, replay stale quantities, and hide the products that are actually exposed.
| Failure | Safe connector behavior | Operator evidence |
|---|---|---|
| Throttled or unavailable API | Queue by account and priority, honor retry signals, add jittered backoff, stop hot loops, preserve newer desired state, and reduce exposure under an approved stale-stock policy | Oldest pending change, affected sellable units, limit headroom, attempt history, next retry, products at risk, and manual action |
| Unknown or ambiguous SKU | Do not guess. Quarantine the order or stock event, prevent publication for the unresolved mapping where necessary, and assign an owner | Raw identifiers, candidate matches, account, listing, quantity, order deadline, customer impact, and resolution history |
| Out-of-order or duplicate event | Use version, event time, source sequence, current ledger state, and idempotency key to ignore duplicates and reject or re-evaluate stale transitions | Event envelope, deduplication decision, prior state, resulting state, rule version, and correlation chain |
| Rejected quantity update | Classify retryable transport errors separately from validation, authorization, listing, policy, and item-state errors; do not retry permanent failures blindly | Request, sanitized response, platform code, desired and observed state, listing issues, owner, and repair path |
| Reconciliation mismatch | Recompute from authoritative inputs, identify whether source, mapping, policy, pending write, remote edit, or order timing explains the drift, then repair deliberately | Both states, input versions, event timeline, difference, exposure, cause, correction, and verification |
API budgets are part of correctness. Shopify's official guidance uses calculated query cost for GraphQL, notes that limits can be reduced temporarily, and recommends queuing and responsible retry. Limit values and platform behavior can change, so read response metadata rather than hardcoding a permanent throughput assumption. Shopify API limits.
Test orders, not only inventory updates
The outcome is a fulfillable order with correct stock ownership. Test complete timelines across warehouse, connector, marketplace, customer action, and recovery.
Concurrency
Two channels sell the last unit; duplicate order notification; late cancellation; reservation timeout; WMS adjustment during allocation; bundle components shared by offers.
Identity
SKU reused, variation remapped, listing recreated, warehouse location retired, product merged or split, barcode duplicated, inactive user owns an offer.
Platform behavior
Throttle, timeout after accepted write, token expiry, permission revoked, validation warning, listing suppression, partial bulk result, webhook replay, delayed report.
Warehouse lifecycle
Receipt, transfer, quality hold, damage, stocktake, pick, short pick, shipment, return in transit, return inspection, restock, and write-off.
Recovery
Connector outage, queue replay, stale snapshot, lost webhook subscription, database restore, adapter deployment rollback, poisoned mapping, and credential rotation.
Acceptance
No negative authoritative stock, no duplicate reservation, known stale exposure within policy, explainable quantity lineage, reconciled remote state, and owned exceptions.
Operate by inventory exposure, not connector uptime alone
A healthy process can still publish stale stock. Monitor freshness, correctness, business impact, API capacity, and repair progress per account, channel, product, and location.
Freshness
Age from authoritative stock change to accepted marketplace state; queue age; reconciliation age; delayed-event age; stale units exposed.
Correctness
Desired-versus-observed mismatch rate; unexplained negative stock; duplicate reservations; unknown SKUs; listing issue and rejection rate.
Business outcome
Oversales, preventable cancellations, stockout time while stock exists, suppressed listings, lost selling time, manual corrections, and fulfillment misses.
Platform health
Request success by operation, throttle time, available API budget, token and subscription expiry, bulk partial failures, webhook delivery, and report lag.
Recovery
Time to detect, exposure at detection, time to safe state, oldest exception, retry age, reconciliation repair rate, and repeat incident by cause.
Change safety
Adapter and schema versions, mapping changes, policy changes, shadow differences, canary results, rollback readiness, and unreviewed platform deprecations.
Delivery gates from stock model to production
Start with a narrow slice: one stock authority, one channel, representative products, and complete order-to-reconciliation behavior.
Frame ownership
Inventory systems, item and location identities, states, allocation rules, fulfillment modes, order owner, exception owner, service levels, and source-of-truth matrix.
Prove the channel contract
Use sandbox where representative, then a controlled seller account to validate authentication, scopes, schemas, listing prerequisites, notifications, limits, and error behavior.
Build a vertical slice
Connect authoritative stock through canonical ledger, allocation, outbox, marketplace adapter, observed-state capture, order reservation, and reconciliation for selected products.
Exercise failure
Test duplicated and missing events, throttles, timeouts, partial success, stale mappings, concurrent last-unit orders, bundle impact, outage replay, and credential changes.
Shadow and canary
Compare calculated versus current offers without writing, explain every difference, then enable bounded products and channels with explicit stop and rollback criteria.
Operate and extend
Track exposure and business outcomes, review exceptions, rotate access, test recovery, monitor API changes, and add channels only after the canonical model supports their semantics.
Protect the connector's order and customer data
Request the smallest marketplace, store, and warehouse scopes; separate read and write roles where possible; encrypt credentials; validate webhook authenticity; redact logs; and prevent support exports from becoming uncontrolled copies of recipient details.
For EU personal data, document controller and processor roles, purpose, necessary fields, retention, subprocessors, locations, transfers, data-subject workflows, incident handling, and Article 32 security measures. Inventory synchronization rarely needs a permanent copy of every customer field. This is implementation guidance, not legal advice. GDPR official text.
Marketplace inventory sync FAQ
How does marketplace inventory synchronization prevent overselling?
It establishes one authoritative stock ledger, converts physical and operational states into channel-specific sellable quantities, reserves stock when orders arrive, processes changes idempotently, and continuously reconciles channel offers against the source. Safety stock can reduce exposure to latency, but it does not replace correct ownership, event handling, and reconciliation.
Should the WMS, ERP, store, or marketplace own inventory?
Choose one authority for each fact. A WMS commonly owns physical on-hand and warehouse reservations; an order-management layer may own cross-channel allocation; each marketplace owns its accepted listing state and marketplace-managed fulfillment inventory. The connector should publish derived channel offers and observe remote state, not let every system overwrite the same quantity.
Are webhooks enough for reliable stock synchronization?
No. Webhooks and notifications reduce latency, but delivery can be delayed, duplicated, reordered, filtered, or interrupted. Persist every event, deduplicate it, fetch authoritative details where required, and run scheduled reconciliation from API snapshots or reports. The reconciliation path is what detects missed events and manual changes.
How should bundles and kits be synchronized?
Model the bill of materials explicitly. The available quantity of a bundle is constrained by the component with the lowest buildable quantity after reservations and channel allocation. When an order reserves a bundle, reserve its components atomically in the authoritative ledger and recalculate every listing that consumes those components.
Can a connector synchronize multiple warehouses?
Yes, if location identity, fulfillment eligibility, routing rules, transfer state, and channel capabilities are explicit. Some channels accept location-level quantities; others need an aggregated offer. Never sum unavailable, committed, damaged, quality-control, or in-transit stock into an offer unless the merchant’s fulfillment promise deliberately permits it.
When is a custom connector better than a full ERP rollout?
A focused connector is appropriate when product identity, inventory authority, order flow, and exception ownership are stable and the gap is narrow. Choose a broader OMS or ERP when purchasing, planning, accounting, manufacturing, returns, warehouse execution, and many channels need one coordinated operating model. A connector should not become an undocumented ERP by accumulation.
Primary sources and status
Reviewed 2 September 2026. Marketplace API schemas, versions, scopes, limits, notifications, and policies change. Recheck the linked official documentation during implementation. GDPR is binding EU law; Yarify's canonical model, reliability design, and operating recommendations are engineering guidance.
- Amazon Selling Partner API — Notification type valuesOfficial notification semantics for seller-fulfilled quantity changes, FBA availability, listing status, orders, and delayed inventory events
- Amazon Selling Partner API — Product listings lifecycleOfficial guide to product type definitions, catalog data, listings, issues, and event-driven listing notifications
- eBay Inventory API overviewOfficial model for seller SKUs, inventory items, warehouse locations, item groups, marketplace offers, quantity, and listing restrictions
- Shopify — Apps in inventory managementOfficial definitions for inventory items, locations, available, committed, reserved, damaged, safety-stock, quality-control, and incoming quantities
- Shopify — Manage inventory quantities and statesOfficial mutation guidance covering set, adjust, move, activation, compare-and-swap checks, idempotency, and adjustment traceability
- Shopify API limitsOfficial calculated-query-cost limits and guidance to queue, back off, and tolerate temporary throttling
- Regulation (EU) 2016/679 — General Data Protection RegulationBinding EU law relevant when marketplace connectors process customer, recipient, staff, or other personal data