PRD: Omnichannel Sync

Module	Inventory	PRD ID	PRD-SYN-001
Status	No item	FEAT	SYN
Epic	—	Plane	—
Date	2026-07-13	Version	v1.0
Packages	@nx/inventory	URD	SYN
Surface	BackendClient · Owner/Mgr
Owner	Phát Nguyễn

What omnichannel sync is

The merchant connects their storefront on an e-commerce marketplace to BANA as an external sale channel (External Channel). From that moment, BANA is the only place that decides how much that storefront still has to sell.

Every external channel draws from exactly one inventory location (InventoryLocation) of one merchant (Merchant). The channel has no stock of its own: it is simply a place that displays the number of the very same stock item.

The four stock numbers

Lifted from Stock Items & Levels so you do not have to open another PRD. Every item at every location carries four numbers:

Number	What the system calls it	Meaning
On hand	on-hand	Goods physically sitting at the location
Reserved	reserved	Already promised to another document, no longer sellable to anyone else
Available	available	The part still on offer
Incoming	incoming	Already left the source location, not yet arrived at the destination

The invariant, true at every moment:

Available = On hand - Reserved

The marketplace receives exactly the available number, minus a buffer (Buffer) if the merchant sets one.

Why there has to be a single source of stock truth

A restaurant or a retail merchant rarely sells in one place only. The same case of goods in the store room is offered at the counter, on a food-delivery app, and on a marketplace storefront. There is only one store room, but the stock is being promised in three places at once.

Two classic failures show up when there is no single source of stock truth. The first is overselling: a customer orders on the marketplace when the item actually sold out at the counter that morning, and the merchant has to cancel the order and take the reputation hit. The second is phantom stock: two systems write stock to the same storefront, each pushing its own idea of the number, and the figure that finally shows up matches nobody's.

BANA solves this by taking on the role of the single source of stock truth. Every sale channel, the internal counter channels and the marketplace storefronts alike, draws from the same stock table. Orders coming back from the marketplace travel the same sale path as an order at the counter, with no shortcuts.

One item from start to finish

Item Y at location A. The channel is assigned to location A. The buffer starts at 0.

What happens	On hand	Reserved	Available	Buffer	Number pushed
Map item Y to the storefront	50	5	45	0	45
Set a buffer of 3 on Y	50	5	45	3	42
The cashier sells 2 units at the counter	48	5	43	3	40
A marketplace customer orders 2 units	46	5	41	3	38
The merchant accidentally sets a buffer of 60	46	5	41	60	0

• The number pushed is available minus buffer, floored at 0. A negative number is never pushed.
• The 5 units reserved for a counter order are never offered for sale on the marketplace.
• A marketplace order travels the path of a counter order: reserve stock, deduct stock, write the inventory ledger. When it is done, BANA pushes the new number out.

The easiest thing to get wrong

Stock flows one way only, from BANA down to the marketplace

BANA does read back the stock number currently displayed on the storefront, but only to compare it against what it just pushed and raise a warning on a mismatch. The number read back is never written into BANA's stock table.

Writing it back opens the door to phantom stock: the marketplace says 99, BANA records 99, then the next push computes 42 and overwrites it. The two systems fight each other, and the final figure matches nobody.

Consequence: a number someone edits by hand in the marketplace admin console only lives until the next push. To change the number on the marketplace, change the stock or the buffer inside BANA.

1. Goals & Non-goals

Goals

• Let the merchant connect a marketplace storefront to BANA, and map each item on the marketplace to exactly one stock item in BANA.
• Push stock one way from BANA down to the marketplace, never the other way around.
• Push the available number (on hand minus reserved), not the on-hand number.
• Let the merchant set a configurable buffer, defaulting to 0, at channel level and overridable per item.
• Pull orders raised on the marketplace into BANA and run them through the same reserve and deduct path as any normal sale order.
• Push the new number back to the marketplace as soon as an item's stock changes, for any reason.
• Show the merchant the sync history and sync status of every item on every channel.

Non-goals

• Syncing the product catalogue, prices, promotions and images to the marketplace. This PRD is about stock only.
• Money reconciliation and marketplace fees - that belongs to the Finance module.
• Shipping routes and delivery statuses for marketplace orders - that belongs to the Sale module.
• How the available number is computed and how stock is held - that belongs to the Stock Reservation feature and the Stock Items & Levels feature.
• The shape of inventory ledger lines and the reason codes - that belongs to the Inventory Ledger feature.
• The reverse direction (the marketplace writing stock into BANA) - not supported, not now and not later.

2. Success metrics

Metric	Target / signal
Overselling on the marketplace	The number of marketplace orders the merchant cancels for being out of stock trends to 0
Sync latency	After a sale at the counter, the number on the storefront lines back up with BANA within tens of seconds
Item mapping coverage	100% of the items on sale on the storefront are mapped to a stock item in BANA
No phantom stock	No storefront has two systems writing stock to it
Merchant trust	The merchant no longer opens the storefront to fix stock by hand

3. Personas & scenarios

Persona	Goal in this feature
Owner / Manager	Connect the storefront, map the items, set the buffer, follow the sync history
Cashier	Sell at the counter as usual and trust that what was just sold is no longer being offered on the marketplace
Warehouse staff	Handle a marketplace order like any other delivery order, with no manual deduction

Core scenario: the merchant owner connects the marketplace storefront to BANA and maps each item → BANA pushes the available number minus the buffer to the storefront → a customer on the marketplace places an order → the order is pulled into BANA, reserves stock and then deducts stock like a normal sale order, writing the inventory ledger → BANA recomputes the available number and pushes the new figure back to that same storefront → meanwhile, every time the cashier sells an item at the counter, the number on the storefront drops along with it.

4. User stories

#	As a	I want	So that
01	merchant owner	to connect my marketplace storefront to BANA	I no longer sit and fix stock on the marketplace by hand every evening
02	merchant owner	stock already sitting in a customer's cart at the counter to stop being offered on the marketplace	I do not have to cancel a marketplace customer's order
03	merchant owner	to hold back a few units from the marketplace	the counter still has stock when the marketplace is selling fast
04	merchant owner	marketplace orders to deduct stock automatically	my stock book does not drift because someone forgot to deduct by hand
05	merchant owner	to know what number BANA pushed to the marketplace and when	when the figure on the marketplace looks odd I can look it up right away
06	merchant owner	the system to warn me if another piece of software is also writing stock to my storefront	I understand why the number keeps jumping around

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	The merchant connects a marketplace storefront to BANA as an external sale channel. • The connect form has these fields: marketplace (required), storefront name (required), the inventory location this channel draws from (required), the channel's default buffer (optional, defaults to 0). • An external channel always draws from exactly one inventory location. • A channel has two states: Syncing and Paused. Pausing stops BANA from pushing stock but leaves the configuration intact.	🚧	URD-SYN-007
FR-002	Internal sale channels and external sale channels share the same stock table. • Internal sale channels are declared by the merchant. BANA seeds a default set per industry (restaurant: dine-in, takeaway; retail: in-merchant, online), and the merchant can edit them or add their own. • An external channel has no location of its own and no stock number of its own. It is simply a place that displays the available number of the very same stock item.	🚧	URD-SYN-001
FR-003	Each item on the storefront is mapped to exactly one stock item in BANA. • The mapping screen shows two columns, the item on the marketplace and its matching stock item in BANA, searchable by name or code. • One stock item can be mapped to several items across several marketplaces. But one item on one marketplace maps to exactly one stock item. • An unmapped item is not synced and carries an Unmapped tag in the list.	🚧	URD-SYN-008
FR-004	Stock flows one way, from BANA down to the marketplace. • BANA writes stock to the storefront. The stock number displayed on the marketplace is never read back to overwrite BANA. • If someone edits stock directly in the marketplace's admin console, BANA's next push overwrites that number.	🚧	URD-SYN-001 · URD-SYN-006
FR-005	The number BANA pushes to the marketplace is the available number, not the on-hand number. • Available equals on hand minus reserved, taken at the inventory location assigned to the channel. • Stock held for a counter order, for a stock transfer or for a production order is never offered for sale on the marketplace.	🚧	URD-SYN-002
FR-006	The number pushed to the marketplace also subtracts a configurable buffer. • The buffer is set at channel level, defaults to 0, and can be overridden per item on that channel. • The number pushed equals available minus the buffer. If the result is negative, 0 is pushed, never a negative number. • Changing the buffer triggers an immediate re-push for the affected items.	🚧	URD-SYN-003
FR-007	Orders raised on the marketplace are pulled into BANA and become normal sale orders. • A marketplace order is tagged with that external channel as its sale channel, so revenue reporting can be split by channel. • The order travels the same reserve-then-deduct path as a counter order, and writes the inventory ledger like any other deduction. • The same marketplace order, however many times it is pulled in, deducts stock exactly once. • A marketplace order landing on an unmapped item is parked in the orders-to-handle list with a reason. The system never deducts stock blindly.	🚧	URD-SYN-004
FR-008	Right after stock is deducted for a marketplace order, BANA recomputes the available number and pushes the new figure to that same marketplace. • The item is also re-pushed to every other external channel selling the same stock item, so two marketplaces do not both keep offering an item that has run out. • If a marketplace order is cancelled, the stock that was held or deducted goes back to the location and the new number is pushed out again.	🚧	URD-SYN-005
FR-009	Any change to a stock item's stock triggers a re-push to the external channels selling that item. • The triggers: a sale at the counter, goods receipt, stock transfer, stock count, write-off, and orders from the marketplaces themselves. • Several changes in a row on the same item are batched into a single push of the latest number, rather than one push per beat.	🚧	URD-SYN-005
FR-010	A storefront takes stock updates from exactly one source, BANA. • When connecting the channel, the merchant must tick a confirmation that every other piece of software writing stock to this storefront has been removed. • If BANA pushes the number X and a read-back finds the marketplace showing something other than X, with no marketplace order to explain it, the channel raises an Another system is writing stock warning with instructions on what to do. • The warning is there for the merchant to see. It does not switch the channel off.	🚧	URD-SYN-006
FR-011	The merchant can see the sync history of each item on each channel. • Each history line records: the push timestamp, the available number, the buffer subtracted, the final number pushed to the marketplace, and the outcome, Success or Error with a reason. • A failed push is retried automatically. Past the retry limit, the item carries a Sync error tag and the merchant can push again by hand. • The list filters by channel, by item and by outcome.	🚧	URD-SYN-009
FR-012	External channels are per-merchant data. • A user only sees and configures channels belonging to their own merchant. • Deleting a channel is a soft delete. A deleted channel stops pushing stock immediately, and the last number pushed stays put on the marketplace until the merchant edits it themselves.	🚧	URD-SYN-007

5.1 Acceptance criteria

• Go to Sale channels on the Client app, click Connect channel, pick the marketplace, name the storefront and choose location A → the channel is created in the Syncing state, with the buffer showing 0.
• Open the item mapping screen of the channel just connected and map item Y on the marketplace to stock item Y in BANA → the Unmapped tag disappears and item Y joins the synced list.
• Leave an item on the marketplace unmapped and hit sync → that item gets no stock pushed and keeps its Unmapped tag.
• Item Y has on hand 50, reserved 5, buffer 0 → run the sync → the number pushed to the marketplace is 45, not 50.
• Set the buffer to 3 for item Y and save → the system re-pushes immediately and the number on the marketplace becomes 42.
• Set a buffer of 60 on an item with only 45 available → the number pushed to the marketplace is 0, not a negative number.
• Sell 2 units of item Y at the counter on the POS → open Y's sync history → a new push line shows the number 40 with a Success outcome.
• A marketplace order buys 2 units of item Y → the order shows up in the sale orders list tagged with the storefront's channel name → Y's on hand drops by 2 and the inventory ledger gains a new line pointing back at that order.
• Right after the order in the step above, open Y's sync history → a new push line appears for the recomputed available number with the buffer subtracted.
• Pull the same marketplace order in a second time → Y's stock does not drop again and no new inventory ledger line appears.
• Cancel a marketplace order that already deducted stock → Y's stock climbs back by exactly what was deducted, and a new push line appears in the sync history.
• A marketplace order lands on an unmapped item → the order sits in the orders-to-handle list with the reason Item not mapped, and stock is unchanged.
• Map item Y to two storefronts on two different marketplaces, then sell out at the counter → both storefronts receive the number 0.
• Go into the marketplace admin console, edit Y's stock by hand to 999, then sell an item at the counter → BANA's next push overwrites it and the number on the marketplace goes back to available minus the buffer.
• Try to connect a channel without ticking the confirmation that other stock-writing software has been removed → the Connect channel button stays disabled.
• Push the number 42 to the storefront, then let an outside system overwrite it with 99 with no marketplace order behind it → the channel raises the Another system is writing stock warning with instructions, and keeps running.
• Item Y has 45 available → check the POS and the marketplace storefront at the same time → both draw from that same 45, and the storefront has no stock of its own.
• Delete a connected channel → no new push lines appear, and the last number stays put on the storefront.
• The marketplace returns an error for a push → the history line records Error with a reason and the system retries; past the retry limit, the item carries the Sync error tag and a Push again button appears.
• Switch the channel to Paused and sell at the counter → no new push line in the history; switch it back to Syncing → the current number is pushed out right away.
• Log in as another merchant's account → none of the first merchant's external channels are visible.

6. Non-functional requirements

Aspect	Requirement
Strictly one way	There is no path for a stock number from a marketplace to reach BANA's stock table; what BANA takes from a marketplace is orders, push outcomes, and the stock number read back purely to check for the warning - that read-back number is NEVER written into BANA's stock table
Idempotency	The same marketplace order, however many times it arrives, deducts stock exactly once; the dedupe key is the marketplace's order identifier
Latency	From a stock change in BANA to the new number being sent to the marketplace is no more than 60 seconds, when the marketplace is behaving normally
Push batching	Several stock changes in a row on the same item within a few seconds are batched into a single push of the latest number
Fault tolerance	A slow or failing marketplace must never slow down or block selling at the counter; the stock-push queue runs off the sale path
Ordering	For the same item on the same channel, a later number is never overwritten by an older one
Merchant scoping	Every channel, item mapping record and sync history line is scoped to the user's own merchant; deletes are soft deletes
Traceability	Every push stores the available number, the buffer and the final number, enough to explain why the marketplace is showing that figure
i18n	Channel state labels, sync outcome labels and warning messages are bilingual

7. UX & flows

The path of a marketplace order, and the stock-push feedback loop:

Which number gets pushed to the marketplace:

The screens live in the Client app, under Sale channels: a channel list screen showing the storefront name, the marketplace, the location assigned to the channel, the default buffer and whether it is Syncing or Paused; a two-column item mapping screen; and a sync history screen laid out as a table with the columns Timestamp, Item, Channel, Available, Buffer, Pushed, Outcome.

8. Data & domain

Concept	Role
External channel	A marketplace storefront connected to BANA, tied to exactly one inventory location and one default buffer
Item mapping	The pairing of an item on the marketplace with a stock item in BANA; no mapping, no sync
Buffer	The stock held back from the marketplace; set at channel level, overridable per item, defaults to 0
Pushed number	The available number at the channel's location, minus the buffer, floored at 0
Marketplace order	A sale order tagged with an external channel; travels the same reserve and deduct path as a counter order
Sync history	The record of a single push: timestamp, available, buffer, number pushed, outcome
Phantom stock warning	The sign that another system is also writing stock to the storefront, spotted when the marketplace's number drifts from what BANA just pushed with no marketplace order to explain it

Conceptual level only - the full schema and invariants live in the inventory domain model.

9. Dependencies & assumptions

Depends on

#	Feature	What it depends on
01	STK Stock Items & Levels	the source of the on-hand and available numbers pushed to the marketplace.
02	RSV Stock Reservation	the reserved amount is subtracted from the number pushed to the marketplace, and reserving is the first step when a marketplace order arrives.
03	LDG Inventory Ledger	where the deduction for a marketplace order is recorded.
04	LOC Stock Locations	every external channel draws from exactly one location.
05	Sale module	marketplace orders are created and run through the sale order lifecycle like a counter order.

Assumptions

#	Assumption	What breaks if it is wrong
01	The marketplace allows stock to be written from outside and returns a stable order identifier for BANA to dedupe on.	A marketplace that does not accept stock writes cannot be connected at all. An unstable order identifier means the same order deducts stock several times, and stock slides negative for no visible reason.
02	The marketplace can notify BANA of new orders, or BANA polls the marketplace, and that channel's latency sits within what the merchant can accept.	Orders arriving hours late leave the number on the marketplace higher than reality for that whole window, and overselling comes back exactly as it was before the channel was connected.
03	The merchant accepts that the number on the marketplace can lag BANA by tens of seconds, and covers that risk with the buffer.	A merchant expecting instant parity reads every few-second drift as a bug, and the trust in the number on the marketplace is gone.
04	The merchant uses BANA alone to write stock to the connected storefront; every other piece of software has been removed from it.	With two systems writing, the number on the storefront jumps around and matches neither of them, and the phantom stock warning fires constantly with nothing able to fix it.
05	One item on the marketplace corresponds to exactly one stock item, not a bundle that explodes into several stock items.	Selling a bundle on the marketplace leaves no single available number to push, and that item has to stay out of the sync until there is a rule for computing the smallest number the recipe can still make.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory v2) - see the feature URD catalogue
Rollout	Enabled per merchant, when the merchant chooses to connect a channel; existing internal channels are untouched
Migration	There is no legacy external channel data; a channel's first sync pushes every mapped item
Release criteria	The on-hand 50, reserved 5, buffer 3 scenario lands on 42; a marketplace order deducts stock exactly once and re-pushes the new number; a manual stock edit on the marketplace is overwritten by the next push
Monitoring	Marketplace orders cancelled for being out of stock, stock-push latency, push error rate per marketplace, count of unmapped items

References

• URD: Omnichannel Sync
• Related: Stock Items & Levels · Stock Reservation & Oversell Guard · Inventory Ledger · Stock Locations
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	Pushing the on-hand number instead of the available number would re-offer stock already held for a counter order	The number pushed to the marketplace is the available number, with reserved already subtracted (FR-005)
02	Several systems writing stock to one storefront produce phantom stock	A mandatory confirmation at connect time, plus a warning when a drift is spotted with no marketplace order behind it (FR-010)
03	The lag between BANA and the marketplace still lets an oversold order through within a few seconds	The configurable buffer lets the merchant buy themselves extra safety margin (FR-006)
04	A marketplace order pulled in several times would deduct stock several times	Dedupe on the marketplace's order identifier; one order deducts stock exactly once (FR-007)
05	A failing or rate-limited marketplace clogs the stock-push queue and freezes the number on the marketplace	The stock push runs off the sale path, with retries and a Sync error tag the merchant can see (FR-011)
06	Bundles and prepared items on the marketplace do not map one-to-one to a single stock item	Open: decide how to compute the available number for a marketplace item that explodes into several components, based on the smallest number the recipe can still make
07	A merchant selling on several marketplaces could end up offering a sold-out item inconsistently across them	One stock change re-pushes to every channel selling the same stock item (FR-008)

Frequently asked questions

#	Question	Answer
01	Why does BANA push the available number instead of the on-hand number?	Because on hand includes the stock already promised to somebody else. Three cans sitting in a customer's cart at the counter are still on the shelf, but they are already sold. Pushing on hand to the marketplace means offering those same three cans for sale a second time, and that is the single most common cause of overselling.
02	What is the buffer for?	To buy yourself a safety margin. There is always a lag between BANA pushing a number and the marketplace displaying it, and during that window a marketplace customer can still order. Setting a buffer of 3 means "do not offer the last three units on the marketplace, keep them for the customers at the counter". The default is 0, meaning nothing is held back.
03	Can the marketplace write stock back into BANA?	No, and it never will. Stock flows one way, from BANA down to the marketplace. BANA does read back the stock number currently displayed on the storefront, but only to compare it against what it just pushed and raise a warning on a mismatch; the number read back is never written into BANA's stock table.
04	What if I accidentally edit stock by hand in the marketplace admin console?	That number lives until BANA's next push and is then overwritten. To change the number on the marketplace, change the stock or the buffer inside BANA, not on the marketplace.
05	I am also running another marketplace management tool - is that a problem?	Yes. Two systems writing stock to one storefront each push their own idea of the number, and the figure that ends up displayed matches nobody - that is phantom stock. BANA asks the merchant to confirm the other tool has been removed when connecting the channel, and warns if it spots signs that another system is still writing.
06	Do marketplace orders deduct stock differently from counter orders?	No. They travel exactly the path of a counter order: reserve stock, deduct stock, write the inventory ledger. The only difference is the sale channel tag, so revenue reporting can be split by channel.
07	What is a "sale channel" in BANA today?	It is an internal sale channel declared by the merchant. BANA seeds a default set per industry (restaurant: dine-in, takeaway; retail: in-merchant, online), and the merchant can edit them or add their own. The external channels this PRD describes live alongside them and share the same stock table; the only difference is that their number gets pushed out.