How do you design real-time inventory for quick commerce without overselling?

In quick commerce, the customer is not only buying a product. They are buying certainty: "this is available near me and will arrive in minutes". If the app accepts payment for an item the dark store no longer has, the problem does not end with a refund. Support cost rises, app trust drops, the courier moves without value and marketing pays again to recover the same customer.

That is why real-time inventory cannot be treated as a warehouse report. It is part of the shopping experience and checkout. Stock visible in the app must consider customer location, the right warehouse, products in other carts, active reservations, payments, cancellations, pick pack, substitutions and WMS/ERP integration delays.

At GMI Software we design q-commerce as a domain system: React Native or Next.js for a fast front end, MedusaJS where commerce core fits, NestJS for reservation rules and integrations, Redis for short locks, and PostgreSQL/WMS/ERP as the truth and audit layer. Redis speed alone is not enough if you do not know when the lock was created, who released it and how to reproduce the order after failure.

Overselling rarely comes from one "slow endpoint". It is usually a chain of delays: the app shows cached stock, the cart does not reserve the item, payment takes dozens of seconds, WMS sends an update after picking, and ERP corrects in batches. During that window, the last unit can sit in three carts, on a picker terminal and inside a push promotion.

The classic mistake is updating stock only after payment. In q-commerce, that is too late. The item must be reserved or marked as held when the customer enters the real checkout path. That reservation needs a TTL because some carts are abandoned, some payments fail and some orders require substitution.

The second mistake is not separating on hand, available, reserved and committed. "We have 10 units" means little if 4 are in carts, 2 are assigned to orders in picking, 1 is damaged and 3 are available only in another dark store. Real-time inventory must calculate availability, not only physical stock.

Cart reservation must be short, explicit and reversible. In practice this means TTL measured in minutes, not hours. For q-commerce, 3-10 minutes is often enough to complete checkout and payment. If payment does not return in time, the lock expires and the product returns to availability. If payment succeeds, the reservation becomes a committed order.

Redis fits this layer because in-memory operations are fast, and commands such as SET with NX/EX options can create simple locks with expiration. But a Redis lock is an operational mechanism, not the accounting ledger. Final order state, audit and settlement must land in durable storage and finance/warehouse systems.

The key detail is atomicity. You cannot first check "is it available" and then reserve in a separate step if another customer can do the same between those calls. You need atomic decrement, transaction, Lua script or a service that serializes the decision per SKU/location. Otherwise the real-time UI only shows inconsistency faster.

Medusa has an Inventory Module for managing inventory items, stocked quantity, reserved quantity, location levels and availability by stock location. That is a useful base when building headless commerce with multiple warehouses, sales channels and custom storefronts. It also gives the API and modularity needed to integrate an external WMS.

But q-commerce needs rules beyond a standard catalogue. Availability depends on customer address, delivery SLA, courier capacity, picking time, minimum thresholds, substitutions, channel priority, promotion and whether an item is already physically in a pickers basket. We usually keep that logic in NestJS or a custom service above MedusaJS instead of hiding it in the frontend.

A good API should answer business questions, not only technical ones: "can this customer at this address buy 2 units now?", "how long do we hold the reservation?", "what do we show if the last unit is in another customer cart?", "can we suggest a substitute?".

The WebSocket API opens a two-way session between browser or app and server. For q-commerce, that naturally fits live stock, order picking status, courier ETA and substitution messages. Instead of polling, the app can receive an event: "SKU unavailable", "reservation expired", "order accepted".

But WebSockets do not solve overselling. If the backend accepts two checkouts for the last unit, the live UI only tells one customer about failure faster. The order matters: consistent reservation and idempotent checkout first, live notification layer second.

On mobile you also need to design for offline mode, poor network and resume after the app sleeps. React Native should not trust local cart state when the user returns from background. On resume, the app should refresh availability and reservation status from the backend before allowing payment to continue.

Q-commerce checkout has several states: reservation created, payment pending, payment succeeded, order committed, picking started, reservation released, substitution needed, cancelled. If you treat it as one "place order" request, payment failures, client retries and provider timeouts quickly create duplicate orders or dead reservations.

An idempotency key is mandatory for finance and inventory operations. The same checkout retried by the app after timeout must not take stock twice. A payment webhook can also arrive again and should not create another order. Every state transition must be retry-safe.

You also need a reconciliation job: a process that finds reservations past TTL, payments without orders, orders without WMS confirmation and differences between inventory service and the system of truth. Real-time inventory without reconciliation looks good in a demo, but starts leaking after the first promotion weekend.

You cannot run q-commerce without inventory metrics. The minimum set is oversell rate, reservation expiry rate, payment timeout rate, WMS event lag, ERP sync lag, stock correction count, substitution rate, cancelled order rate, unavailable-after-click rate and manual intervention count. Each metric needs an operational owner, not only a technical dashboard.

In practice, tails hurt more than averages. Average WMS lag can be 300 ms, while single 20-second spikes during a promotion destroy checkout. That is why we monitor percentiles, queues, retries, DLQs, time from add-to-cart to payment success and the difference between availability shown to the customer and state at commit time.

For leadership, a simple business dashboard is better: how many orders reservations saved, how many products were released after timeout, how many orders required substitution and how many refunds came from stock errors. That turns architecture into an operational result.

Real-time inventory cost is not mostly about Redis itself. It depends on warehouse count, WMS/ERP API quality, sales channels, mobile requirements, substitution rules, delivery SLA, payments, returns, courier roles, promotions and observability. A simple MVP may have one warehouse and a short hold. A dark-store network needs geofencing, routing and more complex rules.

A sensible first q-commerce scope for mobile and backend often starts around PLN 180,000-320,000: DDT, inventory service, cart reservation, Redis TTL, WMS/ERP integration, checkout idempotency, React Native/Expo or Next.js, monitoring and load tests for critical paths. A larger warehouse network, courier dispatch, marketplace or multi-channel model increases scope.

At GMI we can move to fixed price after DDT because we know systems of truth, integrations, failure modes, volume and MVP priorities. Without DDT, q-commerce estimation is guesswork: everything looks simple until two checkouts fight for the last product.

We start with the process, not the tool. We map where stock comes from, when it is reserved, who can change it, what happens after cancellation, how substitution works, when the customer sees "unavailable" and how warehouse operations see the same cart. Only then do we choose Redis, MedusaJS, NestJS, queues, WebSockets and the data model.

Technically, we often combine React Native/Expo for the app, MedusaJS as commerce core, NestJS as inventory/reservation service, Redis for short locks, PostgreSQL for durable state, an event queue for WMS/ERP and observability for lag and retries. What matters is that reservation logic is testable and independent from one frontend.

For the client, that means fewer operational losses, fewer refunds, better retention and a product that can scale beyond the first warehouse. Source-code ownership and no vendor lock-in matter especially here because inventory rules are the heart of the business, not a store add-on.