Get stock position

Read the current StoreLink inventory snapshot for one SKU across one or more Korral stores, and compute the replenishment gap. Read-only.

WHAT IT RETURNS positions: one entry per requested store, each containing

• store_id The store this row is for, e.g. "47".

• on_hand Units physically in stock at the snapshot time.

• units_sold_last_24h Aggregate units sold in the trailing 24 hours. Aggregate only — there are no baskets, receipts or timestamps behind it.

• gap COMPUTED BY THIS SERVER as units_sold_last_24h - on_hand.

• as_of ISO-8601 timestamp of the inventory snapshot the numbers came from. Stock moves continuously; quote this when you report numbers to the buyer.

All three raw numbers are always returned alongside gap so the buyer can check the arithmetic. Never re-derive gap differently, and never present gap without the on_hand and units_sold_last_24h it came from.

HOW TO READ gap gap > 0 The store sold more in the last 24h than it currently holds. This is the replenishment signal. Magnitude = exactly how many more units would have been needed to serve the last 24 hours out of today's shelf (on_hand 3, sold 11 -> gap +8 at store 47). gap = 0 KNIFE EDGE, not "covered": the shelf holds exactly one more day at yesterday's rate, so the store runs empty in roughly 24 hours (on_hand 7, sold 7 -> gap 0). Surface it to the buyer as a watch item; never report it as fine. gap < 0 Stock exceeds the last 24h of sales by |gap| (on_hand 9, sold 5 -> gap -4). No shortfall indicated. gap is 24-hour arithmetic, not a forecast and not an order quantity. It carries no safety stock, no shelf-capacity limit, no promotion, seasonality or day-of-week adjustment, and no supplier lead time. Never pass gap into create_replenishment_order's quantity as a default — quote it to the buyer as evidence and let them state the number.

WHEN TO USE IT Step 2 of the standard workflow: lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status. Use it to answer "are we short on X?", to compare a SKU across a store list, and ALWAYS immediately before proposing an order, so the reason string on that order cites live numbers. Pass every store the buyer cares about in one call rather than looping.

ERRORS — five distinct failures needing different responses:

• Unknown store_id, or a store this server has no credentials for -> a per-store entry carrying an "error" field; other stores still return normally. Check every entry before summarising; never total or average across entries that carry an error.

• SKU valid but NOT RANGED at that store -> also a per-store "error" entry ("not ranged"). This is not a typo and not transient: that store carries no inventory record for the product, so it cannot be replenished there and the failure is not fixable by retrying or correcting the code. Report it to the buyer and do not call create_replenishment_order for that store.

• "No credentials for store " -> that store has no API key configured here. It says NOTHING about the stock, which may be fine or may be empty. Never present it as a stock answer, never substitute a different store, and never guess. Pass the message to the buyer so they can raise access with Korral IT.

• "Authentication failed for store after key reload" -> the key was already reloaded once and still rejected. Retrying immediately will not help; a short wait might, and if it persists it is a Korral IT matter. Again, this is not a stock answer.

• Unknown sku -> the WHOLE call fails; the code is wrong. Call lookup_sku and retry with a sku copied verbatim from its matches. If EVERY requested store errors, the whole call is returned as an error too — that is a credentials or connectivity problem, so do not report it to the buyer as "no gaps found".

WHEN NOT TO USE IT It does not write anything and cannot reserve, hold or move stock. It has no supplier information (no vendor, lead time, order minimum or cost), no pricing, cost or margin, and no POS or transaction-level detail beyond the single aggregate units_sold_last_24h — no basket data, no hourly breakdown, no history beyond the current snapshot and trailing 24h. Do not offer the buyer a trend, a week-over-week comparison, or a delivery ETA from this tool.