Create replenishment order

Submit a replenishment order for one SKU to one Korral store in StoreLink. This is the ONLY write tool on this server, and it has real-world effect: a submitted order feeds Korral's internal distribution run — stock gets picked and a truck gets loaded against it. Treat every call as physically consequential.

CONFIRM BEFORE YOU CALL Get explicit human approval from the category buyer for this exact combination of store, SKU and quantity before calling. Never infer a quantity the buyer did not state or approve, never round a number up "to be safe", and never batch several stores by calling this repeatedly without confirming each one. If the buyer's instruction is ambiguous about quantity or store, ask — do not call and then report what you did.

NO IDEMPOTENCY — A RETRY LOADS A SECOND TRUCK Every call issues a NEW order_id. There is no de-duplication key, no idempotency token, and no way to ask this server whether an equivalent order already exists — there is no list or search, and get_replenishment_status only works on an order_id you already hold. Calling twice with identical store, SKU, quantity and reason creates two orders and two physical picks. If a call fails, times out, or you cannot tell whether it landed, do NOT call again: tell the buyer exactly what arguments you sent, say you cannot confirm the outcome, and let them check with Korral ops. Retry ONLY when the tool returned an explicit error stating nothing was submitted.

THE reason FIELD IS NOT A FORMALITY reason is required and is stored on the order as the audit trail a human will read weeks later. It must be a specific, human-meaningful sentence citing the actual stock evidence you just read from get_stock_position — the store, the numbers and the gap. Good: "Gap of 8 units at store 47 over 24h: on_hand 3 vs 11 sold, buyer approved 24 units." Rejected: whitespace only, a bare number, or placeholder text such as "n/a", "-", "test", "asap". If you have not called get_stock_position for this store and SKU in this conversation, you do not have the evidence to write a valid reason — go and get it.

reason is also written to the buyer's audit log, verbatim, whether the order is accepted or refused. Do not paste credentials, tokens or anything secret into it.

WHAT IT RETURNS

• order_id Readable, stable identifier, format RPL--, e.g. "RPL-47-001". Keep it — it is the only handle for reading the order back, and you must give it to the buyer.

• status Lifecycle state, always "submitted" at creation.

• confirmation One-line human-readable sentence the buyer can paste straight into Slack. Surface it verbatim.

ACCESS ERRORS — nothing was written Every error that opens "Rejected before submission — NO order was created" is a guarantee: no stock moved, and retrying after fixing the cause is safe. That includes the two credential failures, "No credentials for store " and "Authentication failed for store after key reload". Both are access problems, not stock problems: do NOT reroute the order to a store you can reach, do not lower the quantity, and do not tell the buyer the order was placed. Report the message verbatim and let them take it to Korral IT.

WHEN TO USE IT Step 3 of the standard workflow: lookup_sku -> get_stock_position -> create_replenishment_order -> get_replenishment_status. Use it only after a positive gap (or an explicit buyer instruction) has been established with live numbers and the buyer has approved the quantity. Then hand back the order_id and confirmation line.

WHEN NOT TO USE IT — AND WHAT IT CANNOT UNDO Orders here are APPEND-ONLY. This server has no cancel, no delete, no amend, no quantity change and no reschedule — none of the other three tools can do it either, and there is no hidden path to it. If the buyer wants an order stopped or changed after submission, say plainly that this server cannot do it and they must contact Korral ops directly; do not create a compensating or negative order to "fix" it. It also raises nothing with suppliers: it does not create a purchase order to a vendor, does not know lead times, order minimums, costs, price or margin, and will not tell you when the truck arrives. It also refuses a SKU that is not ranged at the target store — that store carries no inventory record for it. That is a merchandising fact, not a retryable error: report it, and do not substitute a different store or a similar SKU to get the call through. Never call it speculatively, to test the tool, or to "see what happens".