contracts.reverse_economics

Reverse a priced service obligation or a single recognition with correction evidence, preserving history. Resolve dependent payments for whole-obligation reversals; no cash moves.

What it does

Reverse all phases of an independent priced service obligation with correction evidence. Appends compensating outcomes at the correction date without rewriting originals. Unapply or reverse dependent payments first, or set refundSettled to credit a bill or invoice payments already settled: the settled part becomes a refund claim on the same party and right (refundClaims), settled later by an independent payment. Set recognitionOnly: true to reverse only the named recognition, retaining its bill, payments and other service slices.

A recognition accrual already cleared by a bill requires the whole-obligation path. Date it at the original recognition to undo an early recording before amending; then re-record recognition with a fresh source fact. Record replacement phases separately with new source facts at or after the reversal date. Reversing the bill that raised the contract’s attention.priceDiffers resolves that right’s flag unless another unresolved differing bill for the right still stands. Linked consequences, inactive ledgers and future dates refuse.

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.reverse_economics through GET /v1/catalog/commands/{name} before acting.

The envelope may reference a registered source document of kind 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.

FieldTypeRequiredMeaning and accepted values
contractIdstringYesMinimum length: 1.
activityKeystringYesMinimum length: 1.
occurrenceIdstringYesMinimum length: 1.
sourceFactIdstringYesMinimum length: 1.
effectiveAtstringYesFormat: date-time.
evidencearrayYesItems: object. Minimum items: 1.
evidence[].kindstringYesChoose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other".
evidence[].refstringYesMinimum length: 1.
evidence[].signerstringNoMinimum length: 1.
refundSettledbooleanNoMust be true.
recognitionOnlybooleanNoMust be true.

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
reversalIdstringYesMinimum length: 1.
documentIdstringYesMinimum length: 1.
occurrenceIdsarrayYesItems: string.
refundClaimsarrayNoItems: object.
refundClaims[].claimIdstringYesMinimum length: 1.
refundClaims[].componentobjectYes
refundClaims[].component.originLedgerIdstringYesMinimum length: 1.
refundClaims[].component.accountCodeintegerYes
refundClaims[].amountstringYes
repeatedbooleanYes

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.reverse_economics"
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "contractId",
        "activityKey",
        "occurrenceId",
        "effectiveAt",
        "sourceFactId",
        "evidence"
      ],
      "properties": {
        "contractId": {
          "type": "string",
          "minLength": 1
        },
        "activityKey": {
          "type": "string",
          "minLength": 1
        },
        "occurrenceId": {
          "type": "string",
          "minLength": 1
        },
        "sourceFactId": {
          "type": "string",
          "minLength": 1
        },
        "effectiveAt": {
          "type": "string",
          "format": "date-time"
        },
        "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
              }
            }
          }
        },
        "refundSettled": {
          "const": true
        },
        "recognitionOnly": {
          "const": true
        }
      }
    },
    "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 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",
      "required": [
        "reversalId",
        "documentId",
        "occurrenceIds",
        "repeated"
      ],
      "properties": {
        "reversalId": {
          "type": "string",
          "minLength": 1
        },
        "documentId": {
          "type": "string",
          "minLength": 1
        },
        "occurrenceIds": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "refundClaims": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "claimId",
              "component",
              "amount"
            ],
            "properties": {
              "claimId": {
                "type": "string",
                "minLength": 1
              },
              "component": {
                "type": "object",
                "required": [
                  "originLedgerId",
                  "accountCode"
                ],
                "properties": {
                  "originLedgerId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "accountCode": {
                    "type": "integer"
                  }
                }
              },
              "amount": {
                "type": "string"
              }
            }
          }
        },
        "repeated": {
          "type": "boolean"
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}
Navigate documentation

On this page