Update a cost line
Update an existing cost line. The organisation, the cost sheet and the cost item cannot be changed.
Changing quantity recomputes the amount from the stored snapshot rate.
Changing work_date re-resolves the rate from the register, so the line is
repriced against the version in force on the new date.
Authorizations
Session token for authentication.
Path Parameters
The unique identifier for the cost line.
Body
The cost line to update. The organisation, the cost sheet, the cost item and
the rate cannot be changed. Changing quantity recomputes the amount and the
charge from the stored rate and margin. The resolved margin and the charge are
never sent by the client.
Changing work_date re-resolves the rate from the register only where the
line was priced from it — where cost_item_version is set. A line that was
given its rate has no version to re-resolve and no register entry to consult,
so re-dating one moves the date and leaves the price alone.
The cost item cannot be attached or detached either, in either direction: that would change which shape the line is, and with it where its price is allowed to have come from, leaving a frozen rate behind that no longer matches the story.
Not every attribute on this request replaces. It is a PUT, and most of it behaves like one, but four attributes and the three relationships are preserved when omitted rather than cleared. That is deliberate, and it is stated here rather than left to be discovered:
-
Replaced —
quantity,descriptionandmargin_override. Sending one sets it; omittingdescriptionclears it, and sendingmargin_overrideasnullremoves an override that was there.Removing an override re-resolves the line's margin, and where it resolves from depends on the shape. A line that names a cost item goes back to the register as it stands today — that is the one path by which a recorded line's margin moves, and it only happens because somebody explicitly asked for the rate card back. An ad-hoc line has no register to consult, so it resolves from its own frozen
cost_item_snapshot, which never carries a margin of its own and therefore lands on that category's default.margin_overrideisrequiredfor exactly that reason: without it, correcting a quantity would silently clear an override and re-resolve the margin, so the schema makes you say what you mean. Send it back unchanged when you are changing something else. -
Preserved when omitted —
work_date,line_type,rate,cost_item_snapshot, and theorganisation,cost_sheetandcost_itemrelationships. None of these can be cleared, because a line with no work date, no type, no price, no description of what it bought or no sheet to hang on is not a line at all. Absence can therefore only mean "unchanged", and that is what it means. Sending a value that disagrees with what is stored is refused rather than honoured —CH.004.214for the line type,CH.004.216for the rate,CH.004.215for the snapshot on a line that names a cost item, and a mismatch error for the relationships.
The practical consequence: a client that reads the resource and writes the whole of it back gets the same answer under either rule, which is the case worth being safe for. A client assembling a partial body needs to know which group each attribute is in — hence this list.
Response
The updated cost line.
JSON API response object
A cost line — one costed entry on a cost sheet: a quantity of a rate code, priced at the rate that was in force on the day the work was done.
The pricing is a snapshot, on both sides. rate and amount are resolved
once, on write, from the register version in force on work_date, and that
version is referenced by the cost_item_version relationship. margin and
charge — what the line sells for — are frozen at the same moment. None of
them are ever recomputed: revising a rate or a margin in the register changes
what future lines cost and sell for, and leaves every existing line exactly as
it was recorded.
This resource carries monetary values and is permissioned separately from the cost sheet it belongs to.
Related resources that can be included when a cost line is returned.
cost-items and cost-item-versions are both optional on a line, so asking
for either simply yields nothing for the lines that have none — an ad-hoc line
has no rate code, and a line priced on the job has no register version behind
its rate. Neither is an error, and a request for both across a mixed collection
comes back with whatever exists.
An organisation
- Option 1
- Option 2
- Option 3
- Option 4