Cost rates for agents and scripts
A connected AI assistant with write access can manage your cost rates the same way you do in the app. This page assumes you’ve read AI / Agent access.
On this page
Section titled “On this page”- The
costFactorsarea - Attaching and detaching
- Reading full cost correctly
- Guardrails
The costFactors area
Section titled “The costFactors area”Alongside billOfMaterials, assemblyBills, rawMaterials, shopify, and inventory, the app
API has a costFactors area — the catalogue of rates:
await app.costFactors.create({ name: "Dipping labour", kind: "labour", unit: "hour", unitCost: 40 });await app.costFactors.list({ kind: "labour" });list, get, create, update, and delete. Rows come back with the count of bills of materials
and assembly BOMsAssembly BOMThe BOM for an intermediate component you build and then use inside other bills — a lid, a wick assembly, a pre-wired harness. It keeps its own pre-assembled stock and can be a work order item in its own right.Read more → using each cost rate. kind defaults to overhead
and unit to pcs.
Updating a rate re-prices every BOM immediately and moves no existing
work orderWork orderA planned production run: pick materials, build the items, do QC, and complete — all tracked together. Use work orders when you're building stock ahead of demand or running a multi-day project.Read more → — the same two rules the app follows.
Attaching and detaching
Section titled “Attaching and detaching”Attaching lives on the parent, mirroring how materials are added:
// one minute of a $40/hour rate, per finished unitawait app.billOfMaterials.addCostFactor({ id: bomId, costFactorId, quantity: 0.0166667 });await app.assemblyBills.addCostFactor({ assemblyId, costFactorId, quantity: 0.25 });
await app.billOfMaterials.removeCostFactor({ id: bomId, costFactorId });Calling addCostFactor twice for the same cost rate updates the quantity rather than failing, so a
script can safely re-run.
removeCostFactor detaches the cost rate from that BOM only — the cost rate itself stays in the
catalogue.
Reading full cost correctly
Section titled “Reading full cost correctly”Use billOfMaterials.costBreakdown or assemblyBills.costBreakdown to compare live cost with the
saved materials cost. Live uses the components and rates currently available in the app; it is
not a fresh check with Shopify or a record of a past moment. Saved costs can be out of date even
when they are not zero. Reading them does not recalculate or repair them.
An assembly’s effective cost follows its chosen cost method. Its recipe cost shows what its own recipe would cost, with nested assemblies still using their chosen methods. When an assembly is priced from a build, purchase or average, its live materials and additional-cost breakdowns may be unavailable. An unavailable comparison means “cannot compare”, not “no difference”.
The reported difference removes the bill’s own additional costs and the labour and overhead already included in nested assemblies priced from builds or averages. Additional costs within nested assemblies priced from their recipes can remain in the comparison. A reported difference alone does not prove material prices are out of date. Use the full breakdown to explain the figures rather than treating every gap as a problem to fix.
Guardrails
Section titled “Guardrails”- Deleting an attached cost rate is refused. The error names how many bills of materials and how many assembly BOMs still hold it. Detach them first. Work orders never block a delete — each one stored the cost rate’s name and rate, so its history survives.
- Negative quantities are rejected.
- Read-only connections see none of the write actions.
- On a plan below Enhanced the write actions are refused before they run, with a message naming the plan. The reads keep working.