Follow the decision and execution

Read the authorized case at GET /api/cases/{id}. decision.served means the Award has been released to both parties through the Case Page. decision.finality and its hold reasons describe the pinned procedure. Neither fact confirms payment.

Read execution records at GET /api/cases/{id}/executions, then follow each record’s links.self to GET /api/executions/{id}. A record names the exact Award hash and identifies its mode, status, reports, receipt, and payment provenance. The case view includes execution.mode, execution.executionStatus, execution.paymentConfirmed, and the collection link. Operational partner readers receive status metadata with reports, receipts, and attestation text withheld. A served case without a journal entry still projects its selected mode honestly; an authorized initialize command creates its follow-up record.

The four modes

The settlement binding selects the mode. Without a binding, partner-origin cases use partner_executed and hosted cases use decision_only. Callers cannot switch modes in an execution request. Test and synthetic receipts are shown as simulated, with paymentConfirmed: false.

Report performance

An account session with case membership can POST the following to /api/cases/{id}/executions. A partner acting for a side needs an explicit execution:report membership grant. New claimant filings obtain it only when their authorization expressly includes report_execution; existing authorizations and memberships gain no authority. OAuth needs fresh consent to executions:report; previous scopes do not acquire this authority. Include an Idempotency-Key and the current served awardHash.

{
  "action": "report_performance",
  "awardHash": "<served Award hash>",
  "description": "The ordered payment was sent by bank transfer.",
  "reference": "<performance reference>"
}

The response is performance_reported. The other side may POST action: "acknowledge" or action: "dispute", with that report’s reportId, the same Award hash, and an optional reason. The reporting side cannot acknowledge its own report. A report and its response record statements without deciding discharge or reconsidering the Award.

Follow partner execution

Delivery begins at decision_delivered; a release request records execution_pending. The execution clock issues durable reminders. EXECUTION_PARTNER_REMINDER_MS defaults to one day and EXECUTION_PARTNER_OVERDUE_MS to seven days. Each record captures its deadlines on admission. An overdue result does not prove nonperformance.

The dedicated adapter credential may submit action: "partner_receipt" with a provider reference. The server queries the existing partner provider and requires a confirmed reference bound to the exact Award hash. A partner that will not execute may instead submit action: "will_not_execute" with a reason. That attestation closes follow-up as will_not_execute; it cannot erase an unknown or confirmed provider operation.

Both commands require a signature in addition to bearer authentication. Set x-execution-timestamp to the current Unix time in milliseconds and x-execution-signature to the lowercase hex HMAC-SHA256 of canonical JSON containing caseId, awardHash, idempotencyKey, timestamp, and body. Use the presented bearer credential as the HMAC key; the timestamp is a string. The five-minute acceptance window limits replay exposure. Credential revocation is checked again in the commit transaction. A valid signature authenticates the report; receipt verification is separate.

Request a controlled release

A dedicated settlement:execute credential bound to the case’s adapter may POST action: "request_release" and the Award hash. Party sessions and OAuth reporting tokens cannot release provider funds. The existing execution clock also processes authorized Awards.

Ordinary Awards wait through the seven-day stay and timely correction, additional-Award, and appeal requests. A verified Agent-only Award may execute immediately after atomic service when authorized. A vacated Award cannot execute. Every provider uses the same journal and execution fence. A timeout returns an unknown outcome, which must reconcile before any provider-proven safe continuation; a new HTTP key never authorizes a second payment.

Live providers remain off by default. The existing x402r, bilateral, ACP, and Stripe configuration gates still apply. A completed simulation is not a live settlement.

Retries and notifications

Reuse the same key and payload after an interrupted response. A conflicting payload is refused. Current authorization is required on every read and replay. /settlement-executions accepts the new command format as a compatibility alias; its existing digest-bound evaluation input and response remain supported. Use ?view=executions for the new collection representation on that alias. Canonical SDK methods are listAwardExecutions, getAwardExecution, and recordAwardExecution. The local MCP get_case_executions tool reads these records and cannot release funds.

The shared event cursor includes award_execution_updated and award_execution_reminder. Signed partner webhooks notify the integration that the execution record changed; read the authorized resource for current details. Preserve event IDs to suppress duplicate delivery. Award documents remain immutable and link conceptually to this separate execution history.

TypeScript SDK

Save SDK examples at the repository root. Pass the configured PeopleCourtClient from the quickstart, a case ID obtained through your authorized handoff, and a durable idempotency key for each distinct mutation.

import type { PeopleCourtClient } from "./sdk/typescript/src/index.ts";

export async function readDecision(client: PeopleCourtClient, caseId: string) {
  const { data: view } = await client.getCasePreview(caseId);
  return {
    served: view.decision.served,
    finality: view.decision.finality,
    executable: view.decision.executable,
    holdReasons: view.decision.holdReasons,
    executionStatus: view.execution.status,
    operationsUrl: view.execution.links.operations,
    receiptsUrl: view.execution.links.receipts,
  };
}

// Use a separate adapter-bound settlement-execution credential for this read.
export async function readExecution(client: PeopleCourtClient, caseId: string) {
  const { data } = await client.getSettlementExecutionsCanonical(caseId);
  return { operations: data.operations, attempts: data.attempts };
}

// Canonical four-mode records use the caller’s current case-read authority.
export async function readAwardExecutions(client: PeopleCourtClient, caseId: string) {
  const { data } = await client.listAwardExecutions(caseId);
  return data.executions;
}

Report and acknowledge through the typed SDK

Use the reporting party’s client to record performance, then use the other party’s client to acknowledge that exact stored report. Neither step confirms payment by People’s Court.

import type { PeopleCourtClient } from "./sdk/typescript/src/index.ts";

export async function reportThenAcknowledge(
  reportingParty: PeopleCourtClient,
  otherParty: PeopleCourtClient,
  caseId: string,
  awardHash: string,
) {
  const reported = await reportingParty.recordAwardExecution(caseId, {
    action: "report_performance", awardHash, description: "The ordered payment was sent.", reference: "payment-reference",
  }, "performance-report-001");
  const reportId = reported.data.reports[0].id;
  const current = await otherParty.listAwardExecutions(caseId);
  const execution = current.data.executions.find(item => item.id === reported.data.id);
  const report = execution?.reports.find(item => item.id === reportId);
  if (!report) throw new Error("The recorded report is unavailable.");
  const acknowledged = await otherParty.recordAwardExecution(caseId, {
    action: "acknowledge", awardHash: execution!.awardHash, reportId: report.id,
  }, "performance-acknowledgement-001");
  return acknowledged.data.reports.find(item => item.id === report.id)?.responses;
}

Committed receipt commands replay from the journal after current caller and signature validation, even while the provider is unavailable. A changed reference with the same command identity conflicts. Historical v2 operations are projected and adopted with their original provider keys and receipt provenance; adoption does not call a provider. A missing status client preserves unknown-outcome reconciliation. submissionAttempts counts durable adapter invocations, excluding status reads, and is null where historical counts are unavailable.