Quick answer: An inventory sync API keeps stock counts aligned between your online store and point-of-sale system by moving quantity changes in a defined direction on a defined schedule. Decide which system owns the truth for each SKU, choose near-real-time webhooks or batched updates, and write conflict rules before you write code. Without those decisions, the API will faithfully distribute bad counts faster.
Why sync breaks more often than it “just works”
Stores sell on the website, at the register and sometimes on marketplaces. Each channel decrements stock. If two systems disagree, you oversell or strand inventory. Sudden demand spikes (including periods when more shopping moves online during stay-at-home orders) amplify small sync delays into angry customers.
APIs make sync possible. They do not invent business rules. Start with rules.
Plain primers like what is an API help non-engineers follow along. Implementation detail lives in API integration and REST API design habits.
Pick a system of record
Common patterns:
- POS owns in-store SKUs; ecommerce owns warehouse/web-only SKUs
- Mid-layer ERP owns everything; store and POS are slaves
- Ecommerce owns all, POS is a thin client (rarer for multi-register retail)
Write the choice down. Ambiguity creates double adjustments when a manager “fixes” counts in both UIs.
For WooCommerce-heavy shops, also review how the store tracks stock today in WooCommerce inventory before wiring POS events.
Data you must map
At minimum:
- SKU / item id (and who generates new ids)
- Location or stock pool id (store floor, back room, warehouse)
- Quantity on hand
- Quantity reserved / allocated to open orders
- Timestamp of the change
- Reason code (sale, refund, receipt, adjustment, count)
Optional but useful: cost, bins, lot/serial if you sell controlled goods.
Mismatched SKUs are the number one sync failure. Run a one-time reconciliation export before enabling auto writes.
Sync styles
Webhooks / event-driven: POS posts a sale event; middleware decrements ecommerce. Fast, more moving parts, needs retry queues.
Polling batches: Every N minutes pull changes since last cursor. Simpler ops, more lag.
Nightly full reconcile: Safety net that compares totals and flags drift even when events were missed.
Most durable setups use events for speed plus a nightly reconcile for truth.
Shipping and fulfilment APIs sometimes carry quantity side effects too; do not ignore them when orders ship from mixed locations. Related patterns appear in shipping API integration.
Conflict rules (decide before go-live)
Examples:
- If POS and web disagree by small amounts overnight, trust POS for store-fulfilment SKUs
- Never let a stale webhook overwrite a newer count (use timestamps / version numbers)
- Manual cycle counts freeze API writes for that SKU until released
- Negative stock: block web sales at zero vs allow backorder with a flag
Document behaviour for refunds and voided sales. Double increments after a void are classic bugs.
Architecture sketch
- POS emits sale/refund/adjustment
- Middleware validates signature, maps SKU, applies rules
- Ecommerce API updates quantity
- Dead-letter queue captures failures
- Ops dashboard shows lag and error rates
- Nightly job exports both sides and diffs
Custom inventory platforms follow similar ideas; see custom inventory management system when the middle layer becomes the product.
Zapier-style tools can prototype low-volume syncs. They often fall short for high SKU counts or strict ordering; know when to graduate to proper middleware (Zapier is fine for experiments).
Failure handling
Expect:
- POS offline for hours
- Ecommerce API rate limits
- Partial updates (variant A worked, variant B failed)
- Clock skew between systems
Design for:
- Idempotent events (same sale id applied once)
- Retries with backoff
- Alerting when lag exceeds a threshold
- Read-only mode that pauses web selling if sync is stale beyond policy
Silence is the enemy. A quiet broken sync oversells all weekend.
Security
- Unique credentials per integration
- Rotate keys
- Least-privilege API scopes (inventory write without customer PII when possible)
- Audit logs for manual adjustments
- HTTPS everywhere
Inventory endpoints are a fraud surface when they can zero prices or quantities. Treat them like payment-adjacent systems.
Rollout plan
- Read-only mirror for two weeks; compare diffs daily
- Enable writes for a quiet category
- Expand SKUs
- Turn on nightly reconcile alerts
- Train store managers on which screen to trust
Do not cut over every location on a Friday before a holiday.
Metrics that matter
- Sync lag (p50, p95)
- Oversell incidents per week
- Diff SKUs after nightly reconcile
- Manual adjustment volume (high volume can mean distrust of the system)
SKU onboarding workflow
New items should enter one system first (the system of record), then flow to the other with a create event. Dual manual entry is how duplicate SKUs appear with different spellings and break sync forever.
Testing in a sandbox
Use non-production POS and store copies when the vendors allow it. Replay a day of sales events and compare ending quantities. Only then point production credentials at the middleware.
Location-level inventory pools
Retailers with several stores should sync per location when online orders can ship-from-store or pick up in a specific branch. A single national quantity that ignores store A vs store B creates impossible pickup promises.
Define whether web stock is a sum of stores, a central warehouse only or warehouse plus a buffer. Publish that rule to customer service so agents explain delays the same way the API behaves.
Observability
Log correlation ids from POS event to ecommerce write. When a merchant says “SKU 123 is wrong,” you need to see the last five events for that SKU in one place. Spreadsheet archaeology does not scale past a few dozen items.
Vendor SLA questions
Ask POS and ecommerce vendors about rate limits, webhook retries and sandbox availability before you sign off on a go-live date. An API that cannot replay missed events will force manual counts after every outage.
Cutover communication
Tell store managers the go-live hour, which screen to trust for counts and who to call if the floor quantity looks wrong. Silence during cutover creates parallel spreadsheet inventories that fight the API for weeks.
Business continuity
If the middleware dies, decide in advance whether the website should sell only warehouse stock, switch to manual mode or pause selling for affected SKUs. Write that playbook before the outage, not during Saturday lunch rush.
FAQ
Real-time or every 15 minutes?
If you sell fast-moving goods in-store and online from one pool, aim for event-driven updates. Batching can work for slow SKUs or separate warehouses.
What about marketplaces?
Treat each marketplace as another channel with its own allocated quantity or buffer. Blind one-to-one mirrors across three marketplaces without buffers create oversells.
Can we sync without middleware?
Point-to-point plugins exist. Middleware wins when you have multiple locations, custom rules or audit needs.
Who fixes mismatches?
Name a role. Sync without ownership becomes everyone’s quiet problem.
Align counts on purpose
An inventory sync API is a contract about truth, timing and failure. Settle ownership and conflict rules, then automate. If you want help designing integrations that keep store and POS stock honest, see Automate the busywork.
