Skip to main content

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.

Required scope: accounting:write

Grant 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_note or other (ignored).
    • each line: { kind, description?, sku?, supplier_sku?, quantity?, unit_price?, amount? }; kind is product, freight, duty, fee, insurance, discount, tax (excluded) or other. amount is 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_based or weight_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​

OK

Response Headers
    Content-Type