Operating bulk bill-builder rules

The bulk BOM builder fills a grid of finished goods from rules: when a row’s product title, variant title or SKU looks like this, put these components in, at these quantities. Rules are saved for your shop and reused every season.

A connected assistant can read that rule catalogue and, with write access, write to it: create a rule, correct one, delete one. This is useful precisely because a rule is a fiddly document to author by hand — describing one in a sentence and having the assistant write it is often quicker than filling in the editor.

On this page

• What it takes
• Reading your rules
• Creating a rule
• Correcting a rule
• Deleting a rule
• What it cannot do

What it takes

Reading needs nothing beyond a connection. Creating, changing and deleting a rule need write access. No plan gate — the bulk builder is open on every plan, and so is this.

Reading your rules

The assistant lists every saved rule for the shop, ordered by name, with the full definition of each: what it matches and what it puts in. It can also read one rule on its own.

Note

A rule that no longer makes sense is still listed. If a saved rule’s stored definition can no longer be read, it comes back flagged as invalid with no definition, rather than being hidden or reported as an empty rule. Read that as “this one needs re-saving or deleting”.

Creating a rule

A rule needs a name and a definition. The name is trimmed, at most 100 characters, and unique across your shop regardless of casing — a clash is refused and names the rule you already have, so the right move is to update that one.

The definition has two halves:

• The match checks product title, variant title and SKU. Choose whether all or any fields must match. Each field can also have several conditions with its own all or any choice, up to 20 conditions across the rule. Conditions include does not contain for exclusions. An empty match holds for every row, which is how “fill this whole column” is expressed.
• The actions — at least one: the components to put in, and the quantity each row gets. A quantity is either a fixed number or read out of the row (out of its SKU or its variant title), which is how “a 250 g bag takes 250 g of beans” becomes one rule for a whole size run.

For example, ask: “Create a rule that adds one Cupcake box when the product title does not contain mini and the SKU contains either x or y.” The assistant can resolve your existing Cupcake box material, put both SKU alternatives in one field, and save the rule. It needs the real material’s identifier and title; a guessed identifier will not identify your component when you apply it.

Your assistant uses the same five rule operations as the app: list, get, create, update and delete. Its API description includes the condition format and an example. Saved rules continue to work without conversion. Literal text matching ignores case unless case sensitivity is enabled; patterns keep their casing unless case sensitivity is turned off. A blank SKU matches does not contain any nonempty value.

Open the builder’s Rules list to review what the assistant saved, then choose Apply rules to preview its effect on your rows. Saving the rule alone does not fill the grid or create bills.

Caution

Patterns are checked before they are stored. A pattern used to match a title or to read a number out of a SKU is limited to 200 characters and is refused if it does not compile, or if it is the kind of pattern that can take a very long time to evaluate. The refusal says so — it is not a transient error, and re-sending the same pattern will not help.

A definition containing a field the rule format does not recognise is refused rather than ignored, so a malformed rule fails loudly at save time instead of quietly doing nothing when you apply it.

Correcting a rule

An update can change the name, the definition, or both, and anything you leave out keeps its stored value.

One trap worth naming: a definition you send replaces the stored one entirely — it is not merged branch by branch. An assistant that wants to change one condition must read the rule first and send the whole corrected document back. A capable assistant does this on its own; if you ever see one action survive an edit that should have removed it, that is the mistake to look for.

Renaming onto another rule’s name (in any casing) is refused. Re-casing a rule’s own name is fine.

Deleting a rule

A rule is a saved instruction, never an owner. Deleting one changes no grid and touches none of the bills that rule helped build. There is no preview step and nothing to release.

What it cannot do

• It cannot apply a rule. Applying happens in the builder, in your browser, against the grid you are looking at — with the preview that tells you how many rows match, how many cells would be written and how many of your own hand-typed cells would be kept. An assistant has no grid.
• It cannot create the bills. That is the builder’s Create BOMs step. To have an assistant build bills, use Operating BOMs & assembly bills instead.
• It cannot read or write a saved session. The grid itself is not on this surface.

See also

• Create BOMs in bulk — the page these rules belong to.
• Operating BOMs & assembly bills — building bills directly.