Reviews and disputes

Request a review

Call POST /api/v1/receipts/{receipt_id}/reviews with unit or outcome scope, a reviewer subject and role, a deadline no more than 30 days away, and an on_timeout rule. The response returns an rvq_ review request and one hosted link. The link expires at the deadline and can record one decision.

{
  "scope": { "kind": "units", "units": [3] },
  "reviewer": { "subject": "email:reviewer@example.com", "role": "buyer" },
  "deadline_at": "2026-09-18T12:00:00.000Z",
  "on_timeout": "hold"
}

Confirm or dispute

The hosted page shows the acceptance criteria verbatim, scoped unit results and reasons, evidence digests and provenance, and the deadline. Confirm records human_confirmed with confirmed_by. If confirmation changes a verdict, Spoolis issues a successor receipt with supersedes.reason: review_decision. Confirming an already accepted unit records the decision without issuing another receipt.

A dispute requires a reason and may include text or an HTTPS URL as counter-evidence. The dispute is a dsp_ object. It reports claimed, accepted, disputed, final, and payable figures. While it is open, the policy marks the disputed value as not currently final or payable. Spoolis does not restrict or control money.

Timeout and finality

keep_accepted is valid only when every scoped unit is already accepted. Silence never changes an uncertain or rejected unit to accepted. reject issues a successor receipt. The enum value hold leaves the receipt unchanged and does not describe custody of funds. At the dispute window deadline, the declared finality rule either resolves to the current state or leaves the Spool disputed.

Machine surfaces

The API resources are mirrored by MCP tools request_review, get_review, decide_review, open_dispute, and get_dispute, plus the matching spoolis review and spoolis dispute CLI commands. Receipt status includes pending review and open dispute counts. Consumers can set require_no_open_disputes in requireOutcome and must supply current status.