Item substitutes and alternatives
Set backup items once at the item level so the system already knows the ranked alternative when your first choice runs short, including for manufacturing bills of materials.
Every operation has substitutions that live in somebody’s head: if the 12mm bolts run out, the 12.5mm ones will do. Writing that down once, at the item level, means the system can answer the question instead of the one person who knows.
Set an alternative
“If we run out of 12mm bolts, the 12.5mm ones are the first fallback.”
Three things shape the behaviour:
- Priority ranks the alternatives. Lower is preferred, so priority 10 is chosen before priority 20.
- A conversion factor handles the case where the substitution is not one for one.
- Notes record why the substitution is acceptable, which is the part that saves an argument later.
Two rules are worth knowing before you load a list.
- An item cannot be its own alternative. Self-references are rejected.
- The pair is directional. Recording that A substitutes for B does not mean B substitutes for A, and both directions can exist as separate rows if both are genuinely true.
That second rule catches people out, and it is deliberate. Substitutability is often one-way: the premium part can stand in for the standard one, while the reverse would ship a customer the wrong thing.
Ask what to use
“We need 500 of the 12mm bolts at Main and we are short. What should we use instead?”
This returns the highest-priority active alternative that actually has enough stock at that warehouse, so the answer accounts for reality rather than just preference order. Ties are broken by available quantity, which favours the substitution least likely to run short next.
When nothing qualifies you get a clean empty result rather than an error. No alternative is a legitimate answer, and the caller can act on it.
Review and remove
“What alternatives do we have on file?”
“Drop the 12.5mm bolt as a substitute, it is discontinued.”
Removing soft-disables the row. The substitution stops being offered and the record of it having existed remains, which matters when someone asks why a build in March used a different part.
Manufacturing inherits these
Bills of materials get this behaviour without being configured twice. On the fulfilment side the same list is what a short pick list reaches for, and what you consult before placing a stock reservation you may not be able to honour. When a BOM line has no substitutes of its own, it inherits the item-global alternatives set here. Define the substitution once at the item level and it applies to production as well as to fulfilment, unless a specific BOM line overrides it.
Common questions
Does a lower priority number mean less preferred? No, the opposite. Lower priority is chosen first. Priority 10 beats priority 20.
Why is the relationship directional? Because substitutability usually is. A higher-specification part can often stand in for a standard one while the reverse would be wrong. If both directions are genuinely valid, record both.
What if the substitute is not a one-for-one swap?
Set --conversion-factor when you create the alternative, so quantities translate correctly rather than being assumed equal.
Does the system pick a substitute automatically?
get-best-alternative-for-item gives you the ranked answer with stock taken into account. What you do with it stays a decision, which is the right split for something that changes what a customer receives.
What happens when no alternative has enough stock? You get an empty result, not an error. That is a real answer and the caller can act on it.
Do I have to configure substitutes separately for manufacturing? No. A BOM line with no substitutes of its own inherits the item-global alternatives.
Does removing an alternative delete the history? No, it soft-disables the row so past decisions remain explainable.
Reference: the actions behind this page
You never have to type these. They are what ERPClaw runs when you ask, and they are here for anyone calling the API or MCP surface directly, or reading a log.
add-item-alternative --item BOLT-12MM --alternative BOLT-125MM --priority 10
get-best-alternative-for-item --item BOLT-12MM --required-qty 500 --warehouse "Main"
list-item-alternatives
remove-item-alternative --id <alternative-id>