Core 4/4: Place the order
place_orderCommit a buyer to a quoted purchase under their mandate; the mandate engine returns ordered, pending approval, or refused, and idempotency keys prevent duplicate orders on retry.
Instructions
Order a quote under a mandate. This is the only call that commits the buyer to a purchase.
The mandate engine decides, not you: status ordered (silent/notify), pending_approval (a human must approve at approval_url; poll get_order) or refused (decision.findings say which rule fired). Always send an idempotency_key and reuse it on retries: the same key never orders twice (the retry returns the original order); reusing a key for a different quote fails with idempotency_key_reused. Returns the order (schema /schemas/order.json): id (PO-...), status, decision {outcome, findings}, lines, totals, approval_url when pending, receipt_jws (signed receipt) and, once ordered, erp (the hand-off to Valio Aimo's order system). In this demo erp.status is "simulated" with a SIM- confirmation_id: tell the buyer the order is placed with Sous and the Valio hand-off is simulated, not that Valio confirmed it. rationale: one sentence on why the buyer needs this order; the approver sees it next to the mandate's findings. declared_risks: optional, up to 5 short doubts of your own (as in request_quote); each holds the order for a human. buyer_request: the buyer's own message, verbatim, if you didn't pass it to request_quote (checked the same way). agent_id: optional when your credential covers mandate_id (see my_mandates). agent_token: only if you can't send the Authorization: Bearer header and the mandate requires agent auth.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"mandate_id": "<mandate_id>",
"quote_id": "<quote_id>"
},
"name": "place_order"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | No | ||
| quote_id | Yes | ||
| rationale | No | ||
| mandate_id | Yes | ||
| agent_token | No | ||
| buyer_request | No | ||
| declared_risks | No | ||
| idempotency_key | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| erp | No | Hand-off to Valio Aimo's order system (unsigned): {adapter: stub|http, simulated, status: pending|sent|confirmed|simulated|failed, confirmation_id, note, ...}. simulated=true (status 'simulated', confirmation_id 'SIM-...'): no real order was sent to Valio Aimo (no order API in this demo); describe the order as 'placed with Sous; Valio hand-off simulated in this demo', never as confirmed by Valio. | |
| buyer | Yes | ||
| lines | Yes | ||
| status | Yes | ||
| agent_id | Yes | ||
| approval | No | ||
| decision | Yes | ||
| quote_id | Yes | ||
| order_url | Yes | ||
| amendments | No | Valio's post-order exceptions (short_pick, delay, substitution_at_pick, cancel_line), each {id, kind, line, reason, tier, findings[], status: applied|pending_buyer|accepted|rejected, effect, resolution, jws (typ sous-amendment+jws)} | |
| created_at | Yes | ||
| mandate_id | Yes | ||
| updated_at | Yes | ||
| agent_claim | No | get_order: the agent's rationale, labelled unverified | |
| receipt_jws | Yes | ||
| approval_url | No | ||
| credit_notes | No | Credit (or extra charge) lines from amendments | |
| total_ex_vat | Yes | ||
| delivery_date | Yes | ||
| total_inc_vat | Yes | ||
| agent_rationale | No | ||
| idempotency_key | No | ||
| requested_delivery_date | Yes |