ARCNM Explain Cost
arcnm_explain_costRead-onlyIdempotent
Explain what a manufacturing calculation costs and why, as a concise structured summary: headline unit/total/setup cost, the prediction band, the cost breakdown, the machine used, and the top cost drivers. Pass detail='detailed' for more drivers. Read-only.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | concise | |
| calculation_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| error | No | Why this calculation produced no price, in one sentence, when its status is terminal (failed / cancelled). Absent while it is still running and on a priced calculation. | |
| route | No | Every machine / work centre the priced route runs on, in order — the same chain arcnm_process_plan lists. One entry on a single-machine quote; e.g. [bandsaw, lathe] when the blank is sawn first. Empty when the calculation carries no process plan. | |
| times | No | Time per category behind the cost lines — programming, inspection, finishing, deburring, packaging, and the machine-side phases. Every line except material, tooling and outsourced work is time x rate, so this is the basis the money is struck on. Absent on a calculation that recorded no time breakdown. | |
| status | Yes | ||
| machine | No | Machine the part was priced on. | |
| coverage | No | Present only when status is 'blocked': the calc was created but NOT run because the organization is out of included calculations, has reached a monthly overage cap, or is payment-blocked. Carries {reason, message, remaining, used, included, upgrade_url} — 'reason' says which, and 'message' says how to unblock it. Resolve that, then re-run the saved part. Never a 402; the part is not lost. | |
| currency | No | The calculation's currency. EVERY money figure on this result is stated in it — unit_cost, offer_price, total_cost, setup_cost, the band, every cost_breakdown line and every driver. | |
| guidance | Yes | What to do next to act on or reduce the cost. | |
| lot_size | No | ||
| material | No | Material, when known. | |
| cost_band | No | [low, high] prediction band for the unit cost. | |
| unit_cost | No | Unit cost per part BEFORE the cost-sheet surcharges the costing environment states (overheads, administration and selling, margin, ...). Not the price to quote: that is offer_price, equal to unit_cost only where no surcharges are stated. | |
| confidence | No | Quote-trust signal (calibrated vs model estimate) — read it with the band before trusting the number. | |
| setup_cost | No | One-time setup cost of the lot. Like unit_cost it is stated before the cost-sheet surcharges. | |
| total_cost | No | unit_cost for the whole lot (unit_cost x lot_size), before the cost-sheet surcharges; the lot at the offer price is offer_price x lot_size. | |
| offer_price | No | The offer price per unit — unit_cost plus the cost-sheet surcharges the costing environment states (scrap, overheads, administration and selling, freight, duty, mark-up). Equal to unit_cost when no sheet is stated; this is the figure the tenant's cost sheet and the calculation's own analytics headline as the price. This is the authoritative price: quote from it, not from cost_breakdown.angebotspreis, which is the cost sheet's own total and can differ from it. Absent on older calculations. | |
| top_drivers | No | ||
| unit_time_s | No | Total time per unit in seconds, every work system: the machine run, the finishing pass and the bench work (deburring, packaging) under the allowance, plus the per-unit shares of programming and inspection. Excludes the lot setup (setup_time_s). | |
| cycle_time_s | No | Machining cycle time per unit, in seconds. | |
| needs_review | No | ||
| setup_time_s | No | One-time setup time for the whole lot, in seconds (NOT per unit; divide by the lot size for the per-unit share). Time and cost side by side, for quoting / scheduling / capacity planning. | |
| material_note | No | Plain-language material assumption (which grade was priced, or that a default was used). | |
| calculation_id | Yes | ||
| cost_breakdown | No | Cost figures per unit, keyed by line, all in `currency` (the calculation's currency — the same basis as unit_cost and offer_price, so the lines add up to the headline). The LINES that sum to unit_cost are material_cost, machine_cost, labour_cost, programming_cost, tooling_cost, finishing_cost, inspection_cost, subcontract_cost, overhead_var and overhead_fixed. Six keys RESTATE money already inside those lines and must not be added again: machine_setup_cost and labour_setup_cost are the setup shares machine_cost and labour_cost already include (the tenant's cost sheet shows the same money as a separate 'setup' row and correspondingly smaller machine and labour rows); transfer_cost is the inter-machine hand-off charge on a composed route, which is priced inside overhead_fixed; and material_purchased_cost and remnant_credit derive material_cost, which is material_purchased_cost minus remnant_credit — the stock bought, less what its reusable remnant is worth back in stock (0 unless the costing environment credits remnants). scrap_credit is what the scrap fetches (0 unless the environment credits scrap): a cost-sheet rung SUBTRACTED inside herstellkosten, before scrap_cost and material_overhead are struck on the net material. direct_unit_cost, herstellkosten, selbstkosten, barverkaufspreis and zielverkaufspreis are SUBTOTALS; angebotspreis is the cost sheet's own offer-price total — offer_price is the authoritative price and the one to quote from, and the two can differ; scrap_cost, material_overhead, production_overhead, sga_cost, packaging_cost, freight_cost, duty_cost, margin (the profit mark-up on selbstkosten), cash_discount, sales_commission and customer_discount are the cost-sheet rungs between unit_cost and offer_price. cost_categories holds the sheet's buckets as the page shows them (setup separate); for the itemised sheet with the tiers beneath each line use arcnm_cost_breakdown. | |
| machine_time_s | No | Machine time per unit in seconds: the billed run plus the finishing pass, under the allowance — the time one piece occupies the machine, and the t_e the product's cost sheet states. | |
| review_reasons | No | ||
| cost_categories | No | The cost sheet's own buckets per unit (material, setup, machine, labour, programming, tooling, finishing, overheads …) in the quote's currency — exactly the lines the product shows, setup as its own line. Absent on calculations priced before the sheet existed. | |
| material_resolved | No | False when no material grade resolved and the part was priced on the environment's default — set material_ref and re-run to correct. | |
| selection_failure | No | The same refusal as data when no machine in the costing environment could make the part: the requirement that stopped it, the machine that came closest with its measured values, and how much of the fleet shares the blocker. Absent unless that is why it failed. | |
| assembly_completeness | No | ASSEMBLIES ONLY. Whether `unit_cost` is a price or a LOWER BOUND. Carries {n_unique, n_priced, n_pending, n_unpriced, total_is_lower_bound, priced_complete, unpriced[]}, where each unpriced entry has a closed-enum `reason_code`, a `by_design` flag and, where one exists, a `remedy`. **When `total_is_lower_bound` is true the cost is incomplete: qualify it, never quote it as the price.** A `by_design` reason (a part budget, a plan quota, a cancellation) is the platform working as intended, not a defect — report it as a limit the user can lift, not as a failure. | |
| costing_environment_id | No | The costing environment this was priced in — pass it to arcnm_cost_factors to read the adjustable factors behind these numbers, their range and where each one is saved. | |
| inputs_changed_since_run | No | Null when this price reflects every input on its part revision. Otherwise {roles, corrections, latest_at}: files attached and corrections applied to the part after the run read its inputs, which a new calculation reads and this one did not. | |
| environment_changed_since_run | No | Null when this price was computed on its costing environment as it stands. Otherwise {latest_at}: the environment was edited after the run read it, and a new calculation prices with the current setup while this result does not. |