Skip to main content

Propose Cost Entry Allocations with AI

POST 

/api/cost-entries/:costEntry/ai-allocation

Starts an AI allocation batch for the cost entry. A background job reads the entry's source lines and proposes a product for each line's unallocated amount: deterministic matches first (product on the line, exact SKU, SKU ignoring case, units received on a named purchase order, units returned, earlier confirmations for the supplier), then the AI model picks from close matches for the rest. Every pick is checked against the product's stock and sales in the billed period; lines that cannot be placed are held with a hold code.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Nothing is allocated. Review the proposals, then confirm, edit or reject them. Starting a new batch marks older unfinished proposals of the entry as stale.

No request body.

Returns 202 Accepted with data (the new batch, status pending), tracked_job_log_id (poll GET /api/tracked-job-logs/{trackedJobLog} for progress) and message. Poll Get Latest Cost Entry AI Allocation for the finished proposals.

Errors:

  • 422 with code: no_source_lines when the entry has no source lines to work from (record or import source lines first).
  • When AI cannot run the request is refused and nothing is queued. The body carries message and a machine code:
  • ai_disabled (422) — AI is switched off for the workspace or no API key is set for the active provider.
  • ai_not_permitted (403) — the user's role lacks the ai.use permission.
  • ai_scope_blocked (422) — the workspace has switched off a data type this feature sends to the AI provider. Allocating by hand through the Cost Allocations endpoints stays available in every case.
  • 404 when the cost entry does not exist.

Required permission: cost_entries.ai_allocate (Allocate with AI).

Authentication: Requires Bearer token (scope purchase-orders:write).

Request​

Responses​

Accepted

Response Headers
    Content-Type