contracts.void

Void a contract entered in error: reverse everything it recorded at each fact’s own date and keep its payments as the party’s unapplied funds. Preview first.

What it does

Void a contract that was set up wrongly, so the books read at every date as if it never existed. Every event that posted for the contract is mirrored at its own effective date; payments that settled its claims keep their cash, which becomes the party’s unapplied funds for payments.allocate to match to the replacement contract. The contract becomes voided and accepts no further activity, and the source facts it recorded can be recorded again on another contract (with new idempotency keys). History is kept: nothing is deleted.

Run with preview: true first to see what it reverses and releases, then void with the preview’s planDigest as expectedPlanDigest. Voiding a vendor contract that replaced others restores them.

Refuses discarded drafts, Economico’s own plan contracts, a contract a standing replacement replaced, historical recordings carried out of a closed currency ledger, capacity, ownership, minimum and lifecycle consequences, credit lots, dated quantities, usage reconciliations and the vendor catalog’s other contract events, reversals that owe refunds, cross-currency settlements and contracts with more than 500 events; undo or correct those first.

Before you send it

An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe contracts.void through GET /v1/catalog/commands/{name} before acting.

This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.

Inputs

Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.

Required means required within its containing object; an optional parent can be omitted.

FieldTypeRequiredMeaning and accepted values
contractIdstringYesMinimum length: 1. Example: "ctr_example".
expectedDocumentIdstringYesMinimum length: 1. Example: "doc_contract".
reasonstringYesMinimum length: 1. Maximum length: 500. Example: "set up with the wrong usage metrics".
evidencearrayYesItems: object. Minimum items: 1.
evidence[].kindstringYesChoose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". Example: "other".
evidence[].refstringYesMinimum length: 1. Example: "founder:approval".
evidence[].signerstringNoMinimum length: 1.
previewbooleanNoMust be true. Example: true.
expectedPlanDigeststringNoMinimum length: 1.

After acceptance

When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.

Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.

Result fields

Required means required within its containing object; an optional parent can be omitted.

FieldTypeRequiredMeaning and accepted values
contractIdstringYesMinimum length: 1.
statusstringYesMust be "voided".
voidIdstringNoMinimum length: 1.
reversedEventsintegerYes
occurrenceIdsarrayYesItems: string.
releasesarrayYesItems: object.
releases[].paymentIdstringYesMinimum length: 1.
releases[].claimIdstringNoMinimum length: 1.
releases[].componentobjectNo
releases[].component.originLedgerIdstringYesMinimum length: 1.
releases[].component.accountCodeintegerYes
releases[].amountstringYes
recordedPaymentsarrayNoItems: object.
recordedPayments[].occurrenceIdstringYesMinimum length: 1.
recordedPayments[].sourceFactIdstringYesMinimum length: 1.
recordedPayments[].effectiveAtstringYesFormat: date-time.
recordedPayments[].accountCodeintegerYes
recordedPayments[].directionstringYesChoose "debit", "credit".
recordedPayments[].amountstringYes
recordedPayments[].partyIdstringNoMinimum length: 1.
recordedPayments[].financialAccountIdstringNoMinimum length: 1.
planDigeststringYes
restoresarrayNoItems: string.
previewbooleanNoMust be true.

All commands · Operation and errors · Reusable schemas

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

Exact request schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "const": "contracts.void"
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "contractId",
        "expectedDocumentId",
        "reason",
        "evidence"
      ],
      "properties": {
        "contractId": {
          "type": "string",
          "minLength": 1
        },
        "expectedDocumentId": {
          "type": "string",
          "minLength": 1
        },
        "reason": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "evidence": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "ref"
            ],
            "properties": {
              "kind": {
                "enum": [
                  "tap_message",
                  "x402_receipt",
                  "chain_tx",
                  "signed_doc",
                  "stripe_object",
                  "other"
                ]
              },
              "ref": {
                "type": "string",
                "minLength": 1
              },
              "signer": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        "preview": {
          "const": true
        },
        "expectedPlanDigest": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "effective_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
    }
  },
  "required": [
    "name",
    "input",
    "idempotency_key",
    "effective_at"
  ],
  "additionalProperties": false
}

Accepted command receipt

{
  "type": "object",
  "required": [
    "commandId",
    "replayed",
    "result",
    "events"
  ],
  "properties": {
    "commandId": {
      "type": "string"
    },
    "replayed": {
      "type": "boolean"
    },
    "imported": {
      "const": true,
      "description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
    },
    "result": {
      "type": "object",
      "required": [
        "contractId",
        "status",
        "reversedEvents",
        "occurrenceIds",
        "releases",
        "planDigest"
      ],
      "properties": {
        "contractId": {
          "type": "string",
          "minLength": 1
        },
        "status": {
          "const": "voided"
        },
        "voidId": {
          "type": "string",
          "minLength": 1
        },
        "reversedEvents": {
          "type": "integer"
        },
        "occurrenceIds": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "releases": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "paymentId",
              "amount"
            ],
            "properties": {
              "paymentId": {
                "type": "string",
                "minLength": 1
              },
              "claimId": {
                "type": "string",
                "minLength": 1
              },
              "component": {
                "type": "object",
                "required": [
                  "originLedgerId",
                  "accountCode"
                ],
                "properties": {
                  "originLedgerId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "accountCode": {
                    "type": "integer"
                  }
                }
              },
              "amount": {
                "type": "string"
              }
            }
          }
        },
        "recordedPayments": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "occurrenceId",
              "sourceFactId",
              "effectiveAt",
              "accountCode",
              "direction",
              "amount"
            ],
            "properties": {
              "occurrenceId": {
                "type": "string",
                "minLength": 1
              },
              "sourceFactId": {
                "type": "string",
                "minLength": 1
              },
              "effectiveAt": {
                "type": "string",
                "format": "date-time"
              },
              "accountCode": {
                "type": "integer"
              },
              "direction": {
                "enum": [
                  "debit",
                  "credit"
                ]
              },
              "amount": {
                "type": "string"
              },
              "partyId": {
                "type": "string",
                "minLength": 1
              },
              "financialAccountId": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        "planDigest": {
          "type": "string"
        },
        "restores": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "preview": {
          "const": true
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}

Example request

{
  "name": "contracts.void",
  "input": {
    "contractId": "ctr_example",
    "expectedDocumentId": "doc_contract",
    "reason": "set up with the wrong usage metrics",
    "evidence": [
      {
        "kind": "other",
        "ref": "founder:approval"
      }
    ],
    "preview": true
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "contracts.void-example-0"
}
Navigate documentation

On this page