Reason Codes

One shared list of standard reasons for every business flow: 10 categories (shortage, order cancellation, adjustment, return, damage, hold, cycle count, picking, putaway, disposition), importable with one click, and every business dropdown reads from here.

Reason Codes are shared master data: a standard, reusable list of "why" options for every business flow. Instead of typing free text on each document, people pick a code from a dropdown — so reports always speak the same language. Each tenant keeps its own set, every code has names in six languages (en / zh / es / pt / fr / ja), and the system shows the right language automatically.

Why codes instead of free text#

• Consistent reporting: "Out of stock", "out of stock", "缺货" and "没货" stop being four different buckets — one code, one bucket.
• No hardcoded lists: every reason dropdown in the business pages reads from this master data — add a code here and it appears everywhere, in all six languages.
• History stays readable: deactivating a code hides it from new documents but old ones keep showing the original name.

The 10 categories#

Each category is a tab on the management page. One sentence per category — what it is for, and where it is used:

• shortage · Shortage reasons: used when a WMS shipment comes up short or a mobile short pick is recorded — e.g. "Out of stock", "Oversold (phantom inventory)", "Reserved for another order".
• order_cancel · Cancellation reasons: required when cancelling an OMS order or a WMS appointment — e.g. "Customer requested cancellation", "Payment failed / not received", "Suspected fraud".
• adjustment · Adjustment reasons: recorded when inventory is adjusted up or down by hand in WMS — e.g. "Cycle count variance", "Found stock (unrecorded)", "Scrapped / written off".
• return · Return reasons: used when a return is registered in RMS — e.g. "Defective / faulty product", "Damaged in transit", "Wrong item shipped".
• damage · Damage reasons: used when damaged goods are registered, saying at which stage the damage happened — e.g. "Damaged in warehouse handling", "Forklift / equipment damage", "Water / moisture damage".
• hold · Hold reasons: used when inventory is frozen, saying why — e.g. "Quality hold (awaiting inspection)", "Product recall", "Failed inspection".
• cycle_count · Cycle count reasons: used when registering and posting count variances — e.g. "Count variance found", "Stock found in wrong location", "Count surplus / Count shortage".
• picking · Picking exceptions: recorded when a picking task hits an exception or comes up short — e.g. "Short pick (not enough stock at location)", "Stock not at expected location", "Barcode / label unreadable".
• putaway · Putaway exceptions: recorded when a putaway task hits an exception — e.g. "Target location full", "Location blocked / damaged rack", "Damage found during putaway".
• disposition · Disposition: the handling decision for a return in RMS — e.g. "Restock to sellable inventory", "Refurbish / repair", "Dispose / scrap", "Return to vendor (RTV)", "Donate".

Managing reason codes#

1. Open Master Data → Reason Codes. You will see one tab per category (10 tabs).
2. Click "Import defaults" to load the standard set in one click. The import is idempotent: it only fills in what is missing and never overwrites codes you have renamed or deactivated.
3. New tenants get the defaults automatically when the account is created — no manual import needed.
4. Add your own codes with the New button, rename a code by editing it, and deactivate codes you no longer use instead of deleting them.

How business flows use them#

Every reason dropdown in OMS, WMS, RMS and the mobile app reads this master data — nothing is hardcoded. Maintain the list here and every page picks it up automatically:

• Renaming a code updates its display everywhere at once — including history views (history rows keep the code, not a frozen copy of the name).
• Deactivating a code hides it from new documents only — existing documents keep working and stay readable.
• If several organizations share one tenant setup (3PL), reason codes are tenant-level shared data — all clients use the same set. To distinguish per client, prefix the name, e.g. "Client A — …".

FAQ#

• The default set does not fit my business — can I change it? Yes. Rename, deactivate, or add your own codes freely. A later "Import defaults" only fills in codes that are still missing; it will not overwrite anything you changed.
• Will deactivating a code break old documents? No. Old documents keep their stored code and display it normally; the code just disappears from the dropdown for new documents.
• Do reason codes show in my language? Yes — every code carries names in all six languages, and the business pages display the name in your current interface language automatically.