Inventory Sync Before Black Friday: 5 Edge Cases Your Tests Miss
Last Black Friday, US shoppers spent $11.8 billion online in a single day, according to Adobe Analytics. That's roughly $8.2 million per minute, on average across the day. Every order changes a stock number somewhere. I
Last Black Friday, US shoppers spent $11.8 billion online in a single day, according to Adobe Analytics. That's roughly $8.2 million per minute, on average across the day. Every order changes a stock number somewhere.
If you build order management, inventory management or multichannel software, your synchronization logic probably works fine on a normal Tuesday. Peak traffic is different. It doesn't necessarily create new bugs. It exposes edge cases that never appeared in testing.
TL;DR: calculate stock buffers for fast-selling products, sync every relevant order status change, keep unpaid and returned stock separate, and never rely on webhooks alone. Process events idempotently and run scheduled reconciliation.
Here are five edge cases, why they matter, how to handle them and how to test your implementation before Black Friday. The code is a Python sketch of the pattern, not a ready-made client.
1. Two channels can sell the last unit before your next sync
Shopify sells the last hoodie at 09:00:04. Amazon sells the same hoodie at 09:00:31. Your inventory sync runs every five minutes, so both channels still show one unit available.
Now you have two orders and one item.
On Amazon, this has a direct consequence: sellers must keep their cancellation rate below 2.5%. The metric covers seller-fulfilled orders that the seller cancels before shipping, measured over a seven-day period, so cancelling because of insufficient stock pushes it up.
You cannot make synchronization instantaneous, but you can reduce the quantity exposed on each marketplace.
A common starting point is a buffer for fast-moving SKUs. Instead of always holding back two units, estimate the buffer from sales velocity and synchronization delay. In the sketch below, sales_per_hour is a simplified assumption: the same sales rate on each of the other channels.
import math
def marketplace_quantity(
on_hand,
sales_per_hour,
sync_lag_minutes,
other_channels,
max_buffer=5
):
"""Estimate units to hold back against sales on other channels.
sales_per_hour: assumed rate on EACH other channel."""
expected_elsewhere = (
sales_per_hour
* (sync_lag_minutes / 60)
* other_channels
)
buffer = min(math.ceil(expected_elsewhere), max_buffer)
return max(on_hand - buffer, 0)
marketplace_quantity(
12, sales_per_hour=6,
sync_lag_minutes=5, other_channels=1
) # 11
marketplace_quantity(
12, sales_per_hour=30,
sync_lag_minutes=15, other_channels=2
) # 7
β οΈ This is a simplified heuristic, not a universal inventory formula. Real buffer calculations should account for channel-specific sales rates, shared inventory, fulfillment rules and the possibility of simultaneous orders. A buffer reduces the risk of overselling; it doesn't guarantee that concurrent orders can't exceed available stock.
The cap also matters. Without one, a slow sync on a fast-selling product could hide most of your available stock.
Recalculate sales velocity from recent data rather than last month's average. During Black Friday, yesterday's sales rate may be more useful than last month's.
π§ͺ Test it: sell the same SKU on two channels within one synchronization interval. Check whether the buffer would have prevented the oversell.
2. Cancellations and refunds must reach every channel
A sale reduces stock, and your connector pushes the updated quantity to every marketplace.
Then the customer cancels. Stock returns to your store, but nothing happens on the other channels.
Some integrations process new orders correctly but fail to propagate later order status changes. The result is inventory that is physically available but still invisible on Amazon, eBay or another marketplace.
Two design choices help prevent this:
- Treat inventory changes as a signal to refresh a SKU. Whether the trigger is a new order, a cancellation, a refund with restocking or a manual adjustment, retrieve the current available quantity from your source of truth and update the relevant channels.
- Schedule a full inventory sync. If an event is missed, the next reconciliation can correct the discrepancy.
There is an important distinction between refunds and cancellations. A refund does not necessarily restore inventory. The result depends on the platform and on whether the item was actually restocked.
Always read the resulting inventory quantity instead of assuming that every refund adds one unit back.
π§ͺ Test it: place an order, cancel it and check the marketplace listing. Repeat the test with a refund, and check whether the item was actually restocked, not just refunded. Verify that the correct quantity reaches every channel exactly once.
3. Unpaid orders can reduce stock across every channel
In WooCommerce, an order with the On hold status, such as one waiting for a bank transfer, already reduces stock.
If payment is confirmed, the stock remains reduced. If the order is cancelled, WooCommerce restores it.
This is reasonable within a single store. But if WooCommerce is your source of truth, that lower quantity may be pushed to every connected marketplace.
One customer who never pays can temporarily hide your last available units everywhere, precisely when demand is highest.
Your inventory logic should explicitly define:
- Which order statuses count as committed stock. You may want to treat On hold units as unavailable in the store while handling them differently in your multichannel inventory logic.
- How long unpaid orders remain active. If your business rules allow it, implement a separate cleanup for stale On hold orders created by manual-payment methods. Don't assume WooCommerce's built-in Hold stock timer handles them: that setting applies to eligible Pending payment orders, not to On hold.
- How cancellations propagate. Once an order is cancelled and stock is restored, the updated quantity must reach every connected channel.
The key is to distinguish physical stock from stock reserved by active orders.
π§ͺ Test it: create a bank-transfer order in WooCommerce and leave it On hold. Check the quantity on every connected marketplace. Then cancel the order and confirm that the units become available again.
4. Fulfillment locations and returns belong to separate inventory pools
A single stock number per SKU stops working as soon as inventory is held in more than one place.
Consider a seller using both their own warehouse and Amazon FBA. FBA stock is stored and shipped by Amazon. It should not be mixed with the seller's own warehouse quantity.
Returns introduce another distinction. Amazon evaluates returned FBA items as either:
- Sellable: the item can return to available inventory.
- Unsellable: the item cannot be offered for sale as available stock.
A return that is still being processed is not inventory you can ship.
If your synchronization logic adds every return directly to available stock, you risk selling units that are not ready to fulfill.
Model inventory pools explicitly:
POOLS = {
"own_warehouse": {
"sellable": True,
"channels": {"shopify", "ebay", "amazon_mfn"}
},
"returns_pending": {
"sellable": False,
"channels": set()
},
"amazon_fba": {
"sellable": True,
"channels": {"amazon_fba"}
}
}
def available_for(channel, stock_by_pool):
return sum(
qty
for pool, qty in stock_by_pool.items()
if POOLS[pool]["sellable"]
and channel in POOLS[pool]["channels"]
)
stock = {
"own_warehouse": 10,
"returns_pending": 3,
"amazon_fba": 20
}
available_for("shopify", stock) # 10
available_for("amazon_fba", stock) # 20
β οΈ The example is a simplified scheme that illustrates the principle: calculate availability from the inventory pools that each channel can actually fulfill from. Real FBA availability has more states (reserved units, inbound shipments and others) that this sketch doesn't model.
Move returned units from returns_pending to a sellable pool only after inspection or confirmation from the fulfillment platform.
π§ͺ Test it: process an FBA return and check where the units appear. Verify that they don't become available before Amazon reports them as sellable.
5. Webhooks get missed, retried and duplicated
During a traffic spike, your webhook endpoint can slow down, time out and fail deliveries.
Shopify, for example, retries failed webhook deliveries up to eight times over four hours. If all attempts fail, Shopify stops retrying and may remove the webhook subscription, depending on how it was created. Retries also mean that the same event can arrive more than once. Shopify expects your endpoint to respond within five seconds, so acknowledge the event fast and move the real work to a queue.
This creates two separate problems:
- An event may never reach your application.
- An event may reach your application more than once.
Your integration needs to handle both.
Make webhook processing idempotent
Before anything else, verify the delivery. Shopify signs each webhook with the X-Shopify-Hmac-Sha256 header; check it against the raw request body using Shopify's documented algorithm. Then use X-Shopify-Webhook-Id, which Shopify recommends for detecting duplicate deliveries.
The order of operations matters. If you mark a webhook as processed and the application crashes before the job is queued, the retry will be rejected as a duplicate and the change is lost. Saving the delivery record and the job in one database transaction (an inbox and an outbox) avoids that.
This example handles Shopify's inventory_levels/update topic. Other webhook topics need their own payload mapping.
def handle_inventory_level_webhook(headers, raw_body, payload, secret,
db, verify_shopify_hmac, sku_lookup):
# Header names may arrive lowercased; use a case-insensitive lookup.
h = {k.lower(): v for k, v in headers.items()}
if not verify_shopify_hmac(h.get("x-shopify-hmac-sha256"), raw_body, secret):
return "unauthorized"
webhook_id = h["x-shopify-webhook-id"]
sku = sku_lookup(payload["inventory_item_id"], payload["location_id"])
# Save the delivery and the refresh job together:
# either both are stored or neither is.
with db.transaction():
if not db.inbox_insert_if_new(webhook_id):
return "duplicate"
db.outbox_add("refresh_sku", sku=sku, idempotency_key=webhook_id)
return "accepted" # respond fast; a worker processes the outbox
verify_shopify_hmac stands for an implementation of Shopify's official verification: compute the HMAC from the raw body and your app secret, and compare it with the supplied value using a constant-time comparison. inbox_insert_if_new stands for an insert protected by a unique constraint, not an in-memory set.
Note another detail: inventory webhooks don't necessarily contain the SKU. Shopify's inventory level events, for example, identify the inventory item and the location. Your integration needs a reliable mapping from platform inventory identifiers and locations to its own product records.
Most importantly, don't blindly apply the same inventory delta every time a webhook arrives. Use the event as a signal to refresh the current stock state from your source of truth.
How you write that quantity back depends on the platform and its concurrency behavior. An absolute update can overwrite a newer change if an older value arrives late. A relative update (increase or reduce by N) avoids overwriting changes made by other systems, but it's unsafe if the same event is applied twice. Use idempotency keys, process updates for one SKU in order, and choose the update method each platform handles best.
Also account for event ordering. Shopify doesn't guarantee that webhooks arrive in the order the events occurred; it suggests using the X-Shopify-Triggered-At header or the payload's updated_at to order them. Combined with re-reading the current stock from your source of truth, that keeps stale events from overwriting newer data.
Run scheduled reconciliation
Even reliable webhook processing can't guarantee that your inventory always matches every marketplace.
A reconciliation job compares the expected quantity with what each channel currently shows and corrects the difference. It should count a fix only when the write actually succeeded:
def reconcile(skus, expected_by_channel, channel_quantity,
set_channel_quantity, channels, alert, drift_alert_at=3):
fixed, failed = [], []
for sku in skus:
expected = expected_by_channel(sku)
for channel in channels:
target = expected[channel]
listed = channel_quantity(channel, sku) # None if the read failed
if listed is None: # don't guess
failed.append((sku, channel, "read_failed"))
continue
if listed == target:
continue
# Returns True only when the platform confirms the update.
if set_channel_quantity(channel, sku, target):
fixed.append((sku, channel, listed, target))
if abs(listed - target) >= drift_alert_at:
alert(sku, channel, listed, target)
else:
failed.append((sku, channel, "write_failed"))
return fixed, failed
Alert only when the drift is large; otherwise the alerts get ignored within a week.
In production, reconciliation also needs pagination, retries for the failed list and rate-limit handling. Never treat an unsuccessful API response as a confirmed inventory value.
During peak periods, run reconciliation more often for fast-selling products and less often for the long tail. Keep API rate limits in mind: a full comparison of thousands of SKUs across several channels can generate a lot of requests.
π§ͺ Test it: stop your webhook endpoint for a few minutes, place an order and restore the endpoint. Verify that reconciliation detects and fixes the difference. Then replay the same webhook twice and confirm that inventory isn't reduced twice.
One more thing before the code freeze
None of these cases is particularly exotic. They simply happen too rarely during a normal week to show up in everyday tests.
Test them now: place an order, cancel it, issue a refund, process a return and temporarily stop your webhook endpoint. Finding a synchronization problem during testing is cheaper than finding it through customer complaints on Black Friday weekend.
If you're building inventory synchronization across many platforms, maintaining a separate integration for every marketplace makes this work harder with each one you add. API2Cart provides one API to access orders and update inventory across 80+ shopping platforms and marketplaces, instead of maintaining a separate integration for each. Platform-specific capabilities still matter, but a unified integration layer can simplify the work.
See how inventory synchronization works with API2Cart.
π₯ Prefer video? Here's a 2.5-minute walkthrough of the five edge cases:
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.