Item Recall

The Item Recall entity represents a formal command to withdraw one or more Items from sale or use, typically because they pose a safety, quality, or regulatory risk. It captures why the recall was raised, what must be done about it, and which parts of the retail organization are affected.

An Item Recall can target a specific list of items, optionally narrowed down to individual lots or batches, and can be scoped to one or more Business Units, one or more Business Unit Groups, or a mix of both. This allows a single recall to be issued centrally while still being tracked and actioned at the level where it applies.

Note: Item Recall is distinct from an Item's STOPPED status. The recall entity carries the reason, urgency, impact, and handling instructions behind a recall, while the Item's status reflects the resulting sellability state.

Recall Types

The recall type identifies the underlying hazard or reason that triggered the recall. It helps consuming systems route the recall to the right handling process and communicate risk consistently.

Recall type	Description
CONTAMINATION_BIOLOGICAL	Pathogens, bacteria, mold, or virus contamination. Primary: Food, Cosmetics.
CONTAMINATION_CHEMICAL	Excess heavy metals, restricted phthalates, or toxic residues. Primary: Toys, Clothing, Cosmetics, Food.
ALLERGEN_UNDECLARED	Missing allergen warnings on labels. Primary: Food, Cosmetics.
FOREIGN_MATTER	Physical objects like glass, plastic, or metal fragments found inside products. Primary: Food, Pet Supplies.
DEFECT_MECHANICAL	Structural failures, breaking parts, or assembly flaws. Primary: Furniture, Strollers, Tools, Bicycles.
CHOKING_HAZARD	Detachable small parts or loose components. Primary: Toys, Children's Apparel.
INJURY_SHARP_EDGES	Exposed sharp points, cutting edges, or laceration risks. Primary: Tools, Kitchenware, Toys.
STRANGULATION_SUFFOCATION	Long cords, drawstrings, or airtight packaging issues. Primary: Children's Apparel, Blinds, Bedding.
FIRE_BURN_HAZARD	Overheating, melting components, or flammable fabrics. Primary: Electronics, Apparel, Mattresses.
ELECTRIC_SHOCK	Poor insulation, live wires exposed, or short-circuit risks. Primary: Home Appliances, Lighting, Chargers.
BATTERY_FAILURE	Lithium-ion swelling, leaking, or thermal runaway. Primary: Smartphones, Laptops, E-scooters.
LABELING_MISPRINT	Missing required safety warnings, age-grading errors, or wrong instructions. Primary: All Retail Sectors.
SOFTWARE_BUG	Firmware or software glitches causing safety systems to fail. Primary: Smart Home Devices, Connected Appliances.
CYBERSECURITY_RISK	Vulnerabilities allowing unauthorized control or data leaks. Primary: IoT Devices, Baby Monitors.

Statuses

Status tracks the recall through its lifecycle, from being raised to being fully handled.

Status	Description
RECALLED	The recall is active and must be handled.
READY_FOR_REVIEW	The recall has been actioned at the target scope and is awaiting confirmation or sign-off.
REPEALED	The recall was withdrawn; the underlying reason no longer applies.
CLOSED	The recall has been fully handled and is no longer active.

Urgency

Urgency indicates how quickly the recall must be handled once received.

Urgency	Description
HIGH	The recall must be handled with high priority. This is the default value.
MEDIUM	The recall must be handled, but with less time pressure than HIGH.

Impact

Impact indicates the consequence of not handling the recall.

Impact	Description
HIGH	Failing to handle the recall carries a high impact. This is the default value.
MEDIUM	Failing to handle the recall carries a medium impact.

Closure Reasons

When a recall moves to the CLOSED status, the closure reason records why it was closed. It is not set while the recall is still active.

Closure reason	Description
CLOSED_BY_BUSINESS_UNIT	Closed manually by the Business Unit directly.
CLOSED_BY_MASTER	Closed globally because the master recall itself was closed.
EXCLUDED_FROM_MASTER	Closed because this specific Business Unit or item was removed or excluded from the master recall scope.
REPEALED_BY_MASTER	Closed because the master recall was canceled or retracted globally.

Instructions

Instructions are an ordered, checklist-like list of steps describing how the recall must be handled at the target scope (for example, "Remove item from shelf" or "Verify batch code before disposal"). Each instruction has a step number and a description, and progress against an instruction can be reported back through an Item Recall event-log message.

Scope

An Item Recall must target at least one of:

• One or more Business Units (businessUnitIds)
• One or more Business Unit Groups (businessUnitGroupIds)

Both can be populated on the same recall to combine explicit Business Units with groups.

Recalled Items

Each recalled item is identified by its item id, with optional lists of lot and batch identifiers when the recall applies only to specific production runs rather than the item as a whole.