Record Bill Source Lines
POST/api/bills/:bill/source-lines
Records a whole vendor invoice in one call: the source lines of every cost entry booked from the bill, plus the invoice's detail file, all or nothing. Each entry is named by cost_entry_id or bill_line_id and must belong to the bill. The file is stored once on the bill and linked to every entry; each line points at it.
purchase-orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body: entries (required, 1–200), each with cost_entry_id or bill_line_id, lines (as for Record Cost Entry Source Lines) and optional allocation_mode; optional dry_run. Each line: charge_type (required: product_charge, account_fee, unmatched_reference, rounding, adjustment, other), description (required, ≤500), amount (required, signed, entry currency), basis (required: invoiced = printed on the vendor document; estimated_split = your own split of an invoice charge; computed = e.g. rounding; manual), and optional charge_group (the invoice charge the line belongs to, e.g. "Pallet storage"), external_reference (vendor SKU / code), product_id or product_sku (otherwise a product_charge's external_reference is matched to a product SKU, case-insensitive; no match turns it into unmatched_reference, and an unmatched_reference whose reference does match a product — archived included — becomes a product_charge; recognising a product allocates nothing by itself), quantity, unit, rate, period_start, period_end (Y-m-d, end ≥ start), basis_note (≤500), basis_as_of (ISO 8601 — the snapshot an estimated split was computed from), source_row, metadata (object).
To attach the file, send multipart/form-data with file and the JSON body as a payload field.
Returns the stored document_id and one result per entry. 422 when an entry does not belong to the bill or any entry's lines exceed its amount (nothing is written).
Authentication: Requires Bearer token (scope purchase-orders:write).
Request
Responses
- 201
- 401
- 403
- 404
- 422
- 429
Created
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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
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.