Economicocontracts.cancel
What it does
Cancel a priced-rights contract with evidence and an expected version/state. Records lifecycle without moving money; terminal actions preserve accrued claims. Terminating closes the contract’s credit pools: a refundable lot’s remaining cost is owed back, and overflow the pool still accrues becomes a payable to the vendor, netted into one claim with the refund of the pool’s first lot right.
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.cancel through GET /v1/catalog/commands/{name} before acting.
The envelope may reference a registered source document of kind contract, source_document; this is separate from any evidence required by the input.
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.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
contractId | string | Yes | Minimum length: 1. Example: "ctr_example". |
expectedDocumentId | string | Yes | Minimum length: 1. Example: "doc_contract". |
expectedStatus | string | Yes | Choose "draft", "offer", "active", "rejected", "terminated", "expired". Example: "draft". |
effectiveAt | string | Yes | Minimum length: 1. Example: "2026-10-06T00:00:00Z". |
sourceFactId | string | Yes | Minimum length: 1. Example: "agreement:cancel". |
facts | object | No | |
cancellationAmounts | object | No | |
exchangeRate | object | No | An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store. |
exchangeRate.base | string | Yes | Pattern: "^[A-Z]{3}$". |
exchangeRate.quote | string | Yes | Pattern: "^[A-Z]{3}$". |
exchangeRate.date | string | Yes | Format: date. |
exchangeRate.numerator | string | Yes | Pattern: "^[1-9][0-9]*$". |
exchangeRate.denominator | string | Yes | Pattern: "^[1-9][0-9]*$". |
exchangeRate.evidence | array | Yes | Items: object. Minimum items: 1. |
exchangeRate.evidence[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
exchangeRate.evidence[].ref | string | Yes | Minimum length: 1. |
exchangeRate.evidence[].signer | string | No | |
evidence | object | Yes | |
evidence.acceptance | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
evidence.acceptance[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". Example: "signed_doc". |
evidence.acceptance[].ref | string | Yes | Minimum length: 1. Example: "agreement:cancel". |
evidence.acceptance[].signer | string | No | Minimum length: 1. |
evidence.economic | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
evidence.economic[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
evidence.economic[].ref | string | Yes | Minimum length: 1. |
evidence.economic[].signer | string | No | Minimum length: 1. |
evidence.service | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
evidence.service[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
evidence.service[].ref | string | Yes | Minimum length: 1. |
evidence.service[].signer | string | No | Minimum 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.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
id | string | Yes | Minimum length: 1. |
status | string | Yes | Choose "draft", "offer", "active", "rejected", "terminated", "expired". |
documentId | string | No | Minimum length: 1. |
cid | string | No | Minimum length: 1. |
flags | array | No | Items: string. |
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.cancel"
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"expectedDocumentId",
"expectedStatus",
"effectiveAt",
"sourceFactId",
"evidence"
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"expectedDocumentId": {
"type": "string",
"minLength": 1
},
"expectedStatus": {
"enum": [
"draft",
"offer",
"active",
"rejected",
"terminated",
"expired"
]
},
"effectiveAt": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"facts": {
"type": "object",
"maxProperties": 100
},
"cancellationAmounts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"exchangeRate": {
"type": "object",
"additionalProperties": false,
"required": [
"base",
"quote",
"date",
"numerator",
"denominator",
"evidence"
],
"description": "An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store.",
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"date": {
"type": "string",
"format": "date"
},
"numerator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"denominator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"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"
}
}
}
}
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"acceptance"
],
"properties": {
"acceptance": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"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
}
}
}
},
"economic": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"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
}
}
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"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
}
}
}
}
}
}
}
},
"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))$"
},
"source_document_id": {
"description": "A registered document of kind contract, source_document that caused this command.",
"type": "string",
"minLength": 1
}
},
"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",
"additionalProperties": false,
"required": [
"id",
"status"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"status": {
"enum": [
"draft",
"offer",
"active",
"rejected",
"terminated",
"expired"
]
},
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
},
"flags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}Example request
{
"name": "contracts.cancel",
"input": {
"contractId": "ctr_example",
"expectedDocumentId": "doc_contract",
"expectedStatus": "draft",
"effectiveAt": "2026-10-06T00:00:00Z",
"sourceFactId": "agreement:cancel",
"evidence": {
"acceptance": [
{
"kind": "signed_doc",
"ref": "agreement:cancel"
}
]
}
},
"effective_at": "2026-09-01T00:00:00Z",
"idempotency_key": "contracts.cancel-example-0"
}