The Orders v2 Call Shape

Nearly every call in the Orders v2 stack follows one convention. Stating it once here means the module data-model pages do not repeat it on every row.

The orders-v2 call shape

Mutations are POST /v1/<domain>/<module>/<subject>/<verb>, with the target record’s id in the request body (never a query parameter), plus an effectiveAsOf timestamp (epoch milliseconds). create and add-line calls mint their own id instead of taking one.

Reads are GET .../{eId}, with two optional time coordinates as query parameters: effectiveasof (business time) and recordedasof (system time), both epoch milliseconds. The wire spelling is lower-case — CallFieldNames defines them as "effectiveasof" and "recordedasof"; the camel-case effectiveAsOf / recordedAsOf seen elsewhere are the Kotlin property and sort-field names, not the query parameters. asOf is the name of the object the response carries, not a query parameter at all — the request names the two coordinates separately and the response reports the resolved pair. See the Data Authority API guide for the full bitemporal read contract.

Refusals come back as an HTTP status driven by the failure’s category: 409 for a PRECONDITION failure (a state the caller could have checked first), 403 for a POLICY failure (a rule the caller isn’t allowed to override). Either way, the response carries a stable, documented reason code on the wire — RFrozen, RDemandHeld, RRetiredRef, and so on — so a caller can branch on why, not just that, a call was refused.

Kanban is the one exception. It predates this convention: card events are POST .../{eId}/event/{event} with no body and a single optional effectiveasof query parameter. There is no recordedasof on an event route — verified against the endpoint, which declares only QueryParameter.effectiveAsOf.optional(): system time is the server’s here and a caller cannot set it. An event response returns {event, previous} — the card’s status before the event, not after — which is why every kanban walkthrough step re-reads the card to see the status the event produced.

The refusal mapping is not only a convention of this stack. It is the wire rule of the D13 contract, whose section 2 fixes the same pairing — PRECONDITION to 409, POLICY to 403 — and requires the reason atom to travel verbatim rather than being re-worded per endpoint. A caller branching on RFrozen is reading the contract’s atom, not a string this service chose.

Why the id is in the body

Putting the target id in the request body rather than the path is what lets a mutation carry effectiveAsOf alongside it as one object, so a call names both what it acts on and when it takes effect. A path-addressed mutation would have to carry the timestamp as a query parameter, which is how kanban does it and why kanban reads differently from everything else.

What this page is not

It does not enumerate endpoints. Each module’s data-model page lists its own API surface and links here for the shape those calls share; the data-model reading guide maps those pages.