Analyse Cost Validation Documents
POST/api/ledger/cost-validation/analyse
Analyse supplier documents that were already classified and extracted (purchase invoices, landed-cost bills, credit notes, count sheets) against the account's products and open FIFO layers. Read-only: nothing is saved.
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token + accounting.index permission. Rate limited to 30 requests per minute.
Matching (product lines): a mappings entry, then product SKU, then supplier SKU (the document's supplier first; a code on two products with no supplier to decide is left unmatched), then barcode or MPN. A product with exactly the line's name is only offered as a suggestion.
Landed cost: freight, duty, fees and insurance on a purchase invoice are split over that invoice's product lines; a landed-cost invoice is split over the product lines of the purchase invoices whose number or references match one of its references. Each charge is categorised like a landed-cost bill line and split by its cost category's default method, else by proration. With no proration sent, a freight charge spreads by product weight when every product it covers has a catalog weight above zero, otherwise by value; shared_bill_bases (keyed by landed-cost document) and each history row's freight_bases say which was used. Each product also returns weight_kg, its catalog weight in kilograms (0 when none is set). A landed-cost invoice that cites nothing in the request is returned in unallocated_landed_costs. Credit notes reduce the same product's lines on the invoices they cite. Amounts are converted to the base currency at the document date; a document with no rate is returned in skipped_documents.
Per product: min, unit-weighted median and max landed unit cost; SKU's current cost (average, else unit cost) and the difference from the median; units on hand and coverage (documented units / on hand); status: agrees (current cost within tolerance of the range), differs, no_sku_cost or not_stocked; confidence (high: two or more documents, landed cost included, every extraction at least 0.9; low: an extraction under 0.7; else medium); and the open layers whose unit cost is within tolerance of the range and not already invoice-backed (agreeing_layer_ids, with the unit-cost agreement_bounds they were tested against). Only purchases dated on or after the inventory start date can make a layer agree; earlier or undated purchases are still compared and shown.
Trust: trust.now is cost trust today, trust.if_confirmed is cost trust if every agreeing layer were confirmed.
Purchases before go-live: matched purchase lines dated before the inventory start date are also returned in history_rows, in the history register's purchase-import columns.
Body:
documents(required, 1-500): each{ key (unique), file, pages?, type, supplier_name?, number?, date? (YYYY-MM-DD), currency? (ISO 4217), references[] (other document numbers it cites, max 50), confidence? (0-1), lines[] (max 1000) }.type:purchase_invoice,landed_cost_invoice,count_sheet,credit_noteorother(ignored).- each line:
{ kind, description?, sku?, supplier_sku?, quantity?, unit_price?, amount? };kindisproduct,freight,duty,fee,insurance,discount,tax(excluded) orother.amountis the line total; when missing it is quantity x unit price.
mappings(optional):{ "<supplier SKU or line description>": <product id> }, applied first, case-insensitive (two keys differing only in case are refused).tolerance_percent(optional, 0-25, default 2): how close a cost must be to the documented range to agree.proration(optional):cost_based(default),quantity_basedorweight_based, for landed-cost lines whose cost category has no default split.
Each product's agreeing_layer_bounds gives, per agreeing layer id, the unit-cost bounds that layer was checked against.
Each product's type is the product type (standard, bundle, kit, ...). sku_current_unit_cost is the cost SKU compares (average cost, else default cost). sku_default_unit_cost is the product's default cost (unit_cost, base currency, 0 when none), and sku_default_cost_currency is the currency code when that default cost was entered in another currency (else null): the cost-validation skill proposes a new default cost from these and leaves a foreign-currency one, and bundles and kits (costed from their components), alone.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.