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

• The costFactors area
• Attaching and detaching
• Reading full cost correctly
• Guardrails

Every write here needs the Enhanced plan

create, update and delete on costFactors, and addCostFactor / removeCostFactor on both billOfMaterials and assemblyBills, are Enhanced-plan capabilities — for an agent exactly as for a person in the app. list and get are plain reads and are not gated, so an assistant on any plan can still tell you what your rates are and what they’re costing you.

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

Attaching lives on the parent, mirroring how materials are added:

// one minute of a $40/hour rate, per finished unit
await 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

totalCost excludes additional costs

billOfMaterials.get / .list and assemblyBills.get / .list return a totalCost (and unitCost) that is materials only. It does not, and will not, include cost rates.

To get the full cost to make, use directCostFactorCost — this node’s own cost rates — and recurse into each nested assembly BOM’s own costFactorReferences. Reporting totalCost as the cost of goods understates it by exactly the additional-costs bucket.

This is deliberate: additional costs are computed live and never cached, which is what lets a rate change re-price the whole catalogue instantly. The app’s own Financial breakdown card does the same recursion.

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.

See also

• Cost rates — overview
• What the assistant can read
• Operating BOMs & subassemblies