Shopify sync

Work orders touch Shopify at three moments: when a build run picks materials, when a build run completes (and produces output), and when the work order itself is marked complete (which can write a per-order metafield). Each of these is independent and idempotent — you can retry without double-counting.

On this page

• Pick-time inventory push
• Residual roundingResidual RoundingHow Assemblified handles fractional pick quantities when pushing to Shopify, which only supports whole-number inventory. The integer part is sent to Shopify; the leftover decimal is kept in a local "residual" balance and consumed by future picks before another whole unit gets pushed. Read more → for fractional picks
• Compensation on cancel and reverse
• Completion-time output sync
• The retry banner
• The completion overlay (per-order metafield)
• Tagging linked orders

Pick-time inventory push

When a build run picks Shopify-mapped raw materials, Assemblified pushes a Shopify inventory adjustment to decrement each material at its location. Pre-assembled inventory and virtual materials are not part of this push — they live entirely on Assemblified’s side.

The push happens at pick time, not at completion. The reasoning: once you’ve physically pulled the material off the shelf, Shopify’s count is wrong until you reconcile, even if you haven’t built the units yet.

The push is bundled by (run, location) so a multi-material pick from one location goes out as one call, not many.

Residual rounding for fractional picks

Shopify only accepts whole-number deltas. Work order plans frequently have fractional picks — half a metre of fabric, 1.5 cans of paint per unit, a sub-assembly that draws 0.75 of a parent component.

To prevent long-term drift, Assemblified does this:

1. The fractional delta gets rounded to the nearest integer.
2. The integer goes to Shopify.
3. The leftover decimal is parked in a local residual inventory balance.
4. On the next pick that touches the same material at the same location, the residual is added back into the next delta. Eventually the residual reaches another whole unit and gets pushed.

The total quantity sent to Shopify across all picks of one material always equals the total fractional need, rounded. Local-vs-Shopify never drifts further than one whole unit.

Compensation on cancel and reverse

Cancelling or reversing a build run reverses the Shopify push:

• Cancel (on a picking run) — increments back the materials the pick decremented.
• Reverse (on a built run) — same, plus the completion-time push gets reversed too.

These compensating mutations run automatically as part of the cancel and reverse actions. Status columns on the build run record whether each compensation succeeded so a retry can pick up where things left off.

If the original pick was skipped — a Material List Only work order, a plan with only virtual materials, or Shopify simply not reachable — there is nothing to compensate, and the compensation does nothing.

Completion-time output sync

When a build run completes — or, for a run sent to QC, when a review approves its output — Assemblified forwards the produced output to Shopify through the same dynamic adjustmentDynamic adjustmentA per-bill toggle that recalculates the bill's Shopify-displayed quantity after every order: the bottleneck-resource count plus pre-assembled stock. One of three mutually exclusive toggles — switching it on switches only-sell-pre-assembled and maintain inventory level off. Read more → path that order-driven BOM execution uses. This:

• Pushes the produced quantity onto the bill’s finished-good variant, when that bill has dynamic adjustment turned on.
• Updates any bill set to only sell pre-assembledOnly sell pre-assembledA per-bill toggle (Enhanced plan) that caps Shopify-displayed availability at the pre-assembled stock count. Buildable capacity is hidden — customers can only buy what's on the shelf. One of three mutually exclusive toggles: switching it on switches dynamic adjustment and maintain inventory level off. Read more → so it matches the new pre-assembled stock.
• Cascades to any parent bill that depends on the completed assembly bill.

The completion sync runs independently of the pick-time push. It uses its own status column and can be retried independently if it fails.

The retry banner

If any sync (pick, compensation, or completion) fails, the work order detail page shows one banner headed Shopify did not accept an inventory movement, with a Retry sync button. Press it and Assemblified replays whichever pushes failed, in the right order:

• A previously-succeeded push is skipped.
• A previously-failed push is replayed.
• A push that’s never been attempted (because the prior one failed first) runs for the first time.

The retry is idempotent — replaying a successful push does nothing.

If the retry also fails, the banner stays with Shopify’s own words underneath — that text is the only specific thing there is to go on, so it is shown rather than paraphrased. Reload the app and try once more; if it keeps failing, contact support.

A second, related banner reads Shopify may hold a movement this work order never recorded. That one means Assemblified could not tell whether Shopify applied a push at all. Nothing can settle it from this side, so the banner asks you to check the inventory movements in Shopify — and once you have, its button is Mark as confirmed.

The same Retry Shopify sync action is on each build run’s own ⋯ menu on the Build runs table, for when you want to replay one run rather than the whole work order.

Note

Local state is never rolled back on a Shopify failure. If the pick succeeded locally but the Shopify push failed, Assemblified keeps the local commit and surfaces the banner. Rolling back local state would create a worse problem (the operator already pulled the material off the shelf, and the UI would suddenly say it’s still available). The banner-and-retry pattern is the deliberate choice.

The completion overlay (per-order metafield)

When a work order is created from one or more Shopify orders, completing it triggers a side-effect called the completion overlay. For each linked order, Assemblified writes a material_requirements_json metafield onto the order with:

• The materials the BOM(s) for the order’s variants required.
• Any per-work-order operator notes (lot numbers, specifications, and the build metafields recorded on the Documents & Build Metafields tab).

This is metadata for downstream fulfillment workflows — pickers and shippers can read the metafield to see what materials went into the order. It is controlled by Write material requirements into order metafields, under Settings → Connections → Integrations. If you don’t link a work order to any Shopify orders, the overlay does nothing.

The overlay is fire-and-forget — its errors are logged but don’t affect the work order’s status. If you need to retry it, the only path is to uncomplete and re-complete the work order.

Tagging linked orders

The Tag orders entry in the work order’s More actions menu applies (or removes) Shopify tags on every order linked to the work order. Operators commonly use it to mark orders as “ready to ship” or “in production” once the work order’s status changes.

The dialog shows the current tags on each linked order side-by-side, so you can see the existing state before applying changes. The mutation is the standard Shopify tagsAdd / tagsRemove — no per-order metadata is written here, just tags.

Tagging is allowed on cancelled and completed work orders too — the tags are meta-information that doesn’t affect the work-order state.

What gets skipped, when

A work order inherits its assemble type from the assemble flow it was created from, when it came from one. What each type pushes:

Assemble type	Pick push	Compensation	Completion push	Completion overlay
Pre-Assemble (Physical) — the default	Yes	Yes	Yes	Yes
Bundle/Kit Assemble (Virtual)	Yes (raw materials only)	Yes	No — there is no output to push	Yes
Material List Only	No	No	No	No

For a Material List Only work order, Assemblified records everything on its own side but doesn’t touch Shopify inventory at all. Use it for “shopping list” work orders where you’re tracking what was pulled but not actually changing inventory levels.

Related

• Build Runs — when each push fires and what triggers a retry.
• Material planning & costs — the per-item cost push (a separate action from inventory sync).
• Work-order flows guide — the three modes walked through with sync touchpoints highlighted.
• Glossary.