Marketplace listings and the inventory they will oversell

Trace a single unit through a marketplace sale and the problem becomes obvious. Your integration publishes a quantity. The channel ingests it on its own schedule and caches it behind its own listing infrastructure. A buyer clicks buy. The channel checks its cached number, accepts the order, and some seconds or minutes later tells you about it through an API or a feed. By the time your system learns a unit is gone, the promise has already been made to a customer by a system with no knowledge of what your storefront sold in the meantime.

Nothing on your side of that sequence closes the gap. You can push updates more often, and the channel still sells against whatever it last ingested. You can move from a scheduled feed to an event-driven push, and you have shortened the window rather than removed it. There is no two-phase commit between Shopify and a marketplace, and there is not going to be one, because the marketplace has no incentive to make its checkout wait on your API.

This is worth saying plainly at the start of a project, because a great many marketplace integrations are scoped as though the goal were zero oversell. It is not an achievable goal, and treating it as one produces the expensive version of the build: bidirectional real-time sync, per-event pushes, a queue, retry logic, monitoring for all of it — and still an oversell in the first busy week, now with a larger system to blame.

The achievable goal is different and more useful: keep oversell rare enough that the cost of the cancellations is smaller than the cost of the stock you held back to prevent them. That is an arithmetic question your finance team can actually answer.

Shared pool. Every channel sees the same available quantity. It maximises the stock on display and it is what most integrations do by default, because it is what happens if nobody decides otherwise. Every channel races every other channel for the last unit, and the probability of a collision rises with velocity — which means your best-selling lines, on your busiest days, are precisely where it fails.

Allocation. Each channel gets a fixed quantity that only it can sell. Forty on the storefront, fifteen on the marketplace, five held back. A collision is now impossible, because two channels are never competing for the same unit. The cost is visible and bounded: you are showing less stock than you have, and one channel can sell out while another sits on inventory.

For most mid-market merchants we would argue for allocation, and the reason is not technical elegance. Allocation converts an unpredictable, customer-facing failure into a predictable, internally-visible cost. An oversell produces a cancellation, an apology, a refund, a support ticket and a mark against your seller account. An allocation that ran out produces a line on a report that somebody can rebalance next week. Those are not comparable problems, even when the lost margin is similar.

Allocation is also dramatically cheaper to build. You are publishing a number that changes when you decide it changes, rather than maintaining a low-latency pipeline whose whole value proposition is winning a race it cannot reliably win.

The case for a shared pool is real but narrower than people assume: deep stock relative to daily velocity, slow-moving lines, or a catalogue where a stockout costs more than an occasional cancellation. If you hold three hundred of something and sell four a day, share the pool and stop thinking about it.

Whichever design you pick, you will hold something back. The common implementation is a subtraction buried in the integration — publish available - 3 — which works until somebody needs to know why the marketplace shows three fewer than the admin, and the answer is in a repository they cannot read.

Shopify gives you a better place for it. Its inventory model documents safety_stock as one of the states that make up on-hand, alongside available, committed, reserved, damaged and quality control. A buffer expressed as safety stock is visible in the admin, reportable, and adjustable by the operations team who understand why it exists — without a deployment.

Two practical notes. Committed is Shopify's to manage, through orders and fulfilments, so your integration should never be trying to write it. And the buffer is not a constant: the right number for a line selling four a day is not the right number for one selling forty. Review it per line, quarterly, using the oversell rate rather than intuition.

Everything above concerns races you cannot win. This section is about the ones you can, which is your own systems overwriting each other.

For authoritative writes, inventorySetQuantities sets the available or on_hand quantity to an absolute value. Always send compareQuantity with it. Shopify documents the mutation as updating only if the persisted quantity matches the value you supplied, and the corresponding escape hatch, ignoreCompareQuantity, carries an explicit warning that it "can lead to inaccurate inventory quantities if multiple requests are made concurrently". The documentation's own recommendation is to always include the compare value.

A failed compare is not an error to swallow. It means the world changed between your read and your write — which is exactly the condition you built the integration to notice. Re-read, re-decide, retry. An integration that logs those and carries on is telling you it is losing writes.

For increments and decrements — a return coming back, a count correction — inventoryAdjustQuantities applies a delta rather than an absolute. Deltas are the right instrument for changes you know the size of and the wrong one for periodic sync, because a missed delta is silently permanent while a missed absolute is corrected by the next write.

Batch deliberately, too. Array inputs are documented as capped at 250 items across every Shopify API, and the GraphQL Admin API meters by calculated query cost through a leaky bucket rather than by request count. Both facts point the same way: fewer, larger, well-shaped calls beat a per-SKU loop, particularly during the overnight catch-up when everything runs at once.

Most marketplace integrations subscribe to inventory webhooks — INVENTORY_LEVELS_UPDATE and its siblings, under the read_inventory scope — and treat the payload as the new state of the world. Shopify's own documentation says not to.

Ordering is not guaranteed: "Shopify doesn't guarantee ordering within a topic, or across different topics for the same resource." So two updates to the same item can arrive in the wrong order, and a naive handler will happily write the older one last. Use the X-Shopify-Triggered-At header or the updated_at field to sequence them, and discard anything older than what you have already applied.

Delivery is not guaranteed either — the documentation states plainly that webhook delivery "isn't always guaranteed, and your app can miss or mishandle events". Duplicates need handling as well; X-Shopify-Webhook-Id is what you deduplicate on.

Which leads to the piece that is invariably cut from the first version of the project and added after the first incident: a reconciliation job. Shopify recommends it directly. On a schedule, read the authoritative quantities, compare them with what each channel currently believes, and correct the differences. Log every correction, because the volume of corrections is the honest health metric for the whole integration — a number that starts climbing is telling you something upstream broke weeks before anyone notices a customer complaint.

The request that arrives most often is real-time bidirectional sync across every channel, and we will usually argue against the full version of it. It is the most expensive build available, it is the hardest to test, and its selling point — eliminating oversell — is something it cannot deliver, because the decisive moment happens inside a system you have no API into.

What we would build instead is the smaller thing: clear ownership of the authoritative number, allocation on the lines where velocity makes collisions likely, a buffer somebody adjusts monthly, and reconciliation you can read a graph of. It handles the same volume, it fails in ways you can explain to a customer, and there is less of it to maintain in year two.

If, after measuring, the oversell rate genuinely justifies a lower-latency pipeline on a specific channel, build it for that channel. That is a very different project from rebuilding everything to a standard your least important marketplace does not require — and it is the shape of [integration work](/services/integrate) that survives contact with a peak season.

• Shopify integrations and custom apps
• Inventory truth: the number three systems disagree about
• Webhooks, retries and the orders you never processed