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.
purchase-orders:writeGrant 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_lineswhen 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
messageand a machinecode: 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 theai.usepermission.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
- 202
- 401
- 403
- 404
- 422
- 429
Accepted
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden
Response Headers
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Content
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.