BOM execution end-to-end

This guide walks through a single order from start to finish: a customer places an order containing a BOM-bound variant; Assemblified processes it; a refund happens; the cascade rule plays out. The goal is to give you a mental model of what’s actually happening so you can predict (and debug) any specific case.

On this page

• The setup
• Order placed: what fires
• Pre-assembled drawdown
• Component decrement and Shopify sync
• Dynamic adjustment cascade
• What the log shows
• A refund happens
• What a Keep assembled on return refund looks like

The setup

You sell Vanilla Candle 8oz. It’s a Shopify product with one variant. You have a BOM bound to that variant:

• Direct components:
  • 1 × Glass jar (Shopify-linked raw material)
  • 1 × Vanilla scent oil (virtual material)
• Assembly billSub-assemblyA reusable assembly block that composes into bigger bills: define it once, include it in any bill of materials, and Assemblified expands it into its own components at execution time. The app now calls it an assembly bill. Read more → (the older name is sub-assembly): 1 × “Wick assembly”, which contains:
  • 1 × Raw wick (Shopify-linked, 8% waste)
  • 0.5 × Wick clip (virtual)

Settings:

• Status: Active.
• Pre-assembled quantity: 5 (you built ahead of time).
• Dynamic adjustment: On.
• Keep assembled on return: Off.
• “Wick assembly” pre-assembled quantity: 3.
• “Wick assembly” keep assembled on return: Off.

Shopify variant inventory is currently displayed as 45.

Order placed: what fires

A customer orders 8 units of Vanilla Candle 8oz.

1. Shopify notifies Assemblified that the order changed.

2. Assemblified checks the notification is genuine and ignores it if it has already handled that exact event — a repeat notification never consumes anything twice.

3. It works out what kind of change this is. The order is not cancelled and carries no refunds, so this is a new order.

4. The work is queued, so a failure anywhere downstream can be retried rather than lost.

5. The order is processed. A log row opens, the order’s lines are read, and each is matched against the active bills.

Everything up to this point is plumbing: fast, and no inventory has moved yet.

Pre-assembled drawdown

The handler walks the BOM’s recipe with order quantity = 8.

1. BOM-level pre-assembled. Available = 5. Consume min(5, 8) = 5. Shelf → 0. Remainder = 3.

2. Go into “Wick assembly” for those 3 remaining units (the recipe calls for 1 per candle).

3. “Wick assembly” pre-assembled. Available = 3. Consume min(3, 3) = 3. Shelf → 0. Remainder = 0.

4. It stops there, because the wick assembly’s remainder is zero — its own components are not touched.

5. Direct components for the BOM-level remainder. The glass jar and the vanilla oil are direct components of the BOM, not of the wick assembly, so the wick assembly’s shelf does nothing for them. They are consumed for the 3 units that did not come off the BOM’s own shelf:

   • Glass jar × 3 (1 per unit).
   • Vanilla oil × 3.

Net consumption:

• BOM pre-assembled: -5.
• Wick assembly pre-assembled: -3.
• Glass jar: -3.
• Vanilla oil: -3.
• Raw wick: 0 (covered by the wick assembly’s shelf).
• Wick clip: 0.

Component decrement and Shopify sync

Assemblified builds two lists of changes:

• Shopify-linked changes: Glass jar -3 at the default location.
• Virtual changes: Vanilla oil -3.

The Shopify list is sent in one inventory-adjustment call. The virtual list is applied to Assemblified’s own inventory.

The run’s log records the calculated change per component and whether Shopify accepted it.

Dynamic adjustment cascade

Because the BOM has dynamic adjustment on, Assemblified recomputes the finished good’s displayed Shopify quantity once the consumption is booked. It walks the recipe and asks how many more units it could build from what is left:

Component	Left after the order	Units it supports
Glass jar	87	87
Vanilla oil	97	97
Raw wick (8% waste, inside the wick assembly)	50	50 ÷ 1.08 = 46
Wick clip (0.5 per unit, inside the wick assembly)	100	200

The wick assembly’s own shelf is empty now, so it contributes nothing and the walk continues into its components. The bottleneck is the raw wick: 46. The BOM’s own shelf is empty too, so nothing is added on top.

The new displayed quantity is 46.

It will not match the 45 that was on screen before the order, and that is expected rather than a discrepancy:

• The 45 was the result of the previous recompute, made before this order consumed anything.
• During the order Shopify decremented the finished good by the 8 units sold.
• Dynamic adjustment then sets the quantity to what is buildable now, rather than nudging the old number — so the figure you see afterwards is 46, whatever it was before.

That “set, don’t nudge” behaviour is the single most common source of “the number jumped” questions, and the log is where you confirm it.

What the log shows

The run gets a row in Logs. Open it and the detail page lays out the same story in five cards:

• Summary — the outcome, the type of run, what triggered it, the date, how long it took, the location, the order, and how many retries it took.
• Ordered — the order’s lines, plus which bills were processed and which were skipped and why.
• Material changes — one row per component with its name, SKU, location and the exact calculated change (glass jar −3, vanilla oil −3), and a badge saying whether that change reached Shopify.
• Pre-assembled changes — what came off the shelf as finished stock (5 candles) versus what had to be assembled from components (3), and the assembly bill’s own −3.
• Errors — empty for a healthy run.

The full reading guide is Read and repair the execution logs.

A refund happens

Two days later, the customer refunds 2 units.

1. Shopify sends the order-updated notification with refund line items.
2. Assemblified reads it as a refund, not a new order.
3. It computes what 2 units put back.
4. The cascade rule applies. The BOM’s Keep assembled on return is off and the wick assembly’s is off too, so the units are broken all the way back into raw materials.
5. What comes back:
   • Glass jar +2.
   • Vanilla oil +2.
   • Raw wick + (2 × 1 × 1.08) = +2.16.
   • Wick clip + (2 × 0.5) = +1.
6. Nothing goes back onto a shelf. Because both Keep assembled flags are off, neither the BOM’s pre-assembled stock nor the wick assembly’s is restored — the components are.
7. Shopify is updated with the positive changes, and the virtual materials are updated inside Assemblified.
8. Logistified, if connected, hears the full demand decrease whatever the cascade did. That asymmetry is deliberate: the demand for those components disappeared, wherever the physical units ended up.

A log row is written for the refund like any other run. Assemblified remembers how much of the order has already been refunded, so a later cancellation of the same order does not reverse these 2 units a second time.

What a Keep assembled on return refund looks like

Suppose instead the BOM had Keep assembled on return switched on. The refund of 2 would:

1. Stop the cascade at the BOM.
2. Put 2 units back on the finished-goods shelf. Pre-assembled goes to 2.
3. Change nothing else. Glass jar, oil, raw wick, wick clip and the wick assembly’s own shelf are all untouched.
4. Still report the full demand decrease to Logistified.

This is useful for finished goods that physically can’t be disassembled. The unit goes back to your finished-goods shelf, ready to be re-sold.

Where to next

• BOM execution model — the reference for the pipeline.
• Pre-assembled inventory — drawdown semantics.
• Refunds & cancellations — the cascade rule with worked examples for every branch.
• Read and repair the execution logs — how to read the row this run produced.