Additional costs for agents and scripts

A connected AI assistant with write access can manage your cost factors 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

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 BOMs and sub-assemblies using each factor. 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 factor updates the quantity rather than failing, so a script can safely re-run. removeCostFactor detaches the factor from that BOM only — the factor 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 factors.

To get the full cost to make, use directCostFactorCost — this node’s own factors — and recurse into each sub-assembly’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 Costs tab does the same recursion.

Guardrails

• Deleting an attached factor is refused. The error names how many BOMs and sub-assemblies still hold it. Detach them first. Work orders never block a delete.
• Negative quantities are rejected.
• Read-only connections see none of the write actions.

See also

• Additional costs — overview
• What the assistant can read
• Operating BOMs & sub-assemblies