Economicoingestions.credit_proposal
Prepare a full vendor-credit reversal from a complete retained credit extraction. Returns a proposal only; does not reverse entries or move money.
What it does
Prepare a transient manual full vendor credit reversal from exact complete retained vendor_credit JSON classified credit_or_correction. Source fields: vendor,buyer,externalId,invoiceExternalId,currency,effectiveAt,total,lines:[{description,amount}], optional zero tax/note. Explicit existing priced vendor-service targets must identify one original source-backed invoice billing with the same full amount/currency. All lines reconcile. Only one independent billing phase; service phases, payments/dependencies, partial/taxed credits, PDF/image interpretation and automatic correction require review.
Reuse ordinary contracts.reverse_economics validation, preserve original history and source provenance. Query appends no events, receipt or proposal revision; execute returned command separately with current write authority. Inline text remains unverified.
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 ingestions.credit_proposal 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.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
ingestionId | string | Yes | |
creditText | string | Yes | |
expenseTargets | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
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 |
|---|---|---|---|
disposition | string | Yes | Choose "ready", "needs_information". |
source | object | Yes | |
source.documentId | string | Yes | |
source.cid | string | Yes | |
source.format | string | Yes | Choose "markdown", "text", "document". |
source.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
source.textCid | string | Yes | |
source.location | object | Yes | |
source.location.start | integer | Yes | Minimum: 0. |
source.location.end | integer | Yes | Minimum: 0. |
missing | array | Yes | Items: string. |
original | object | No | |
original.occurrenceId | string | Yes | |
original.documentId | string | Yes | |
original.cid | string | Yes | |
original.sourceFactId | string | Yes | |
original.contractId | string | Yes | |
original.activityKey | string | Yes | |
original.contractDocumentId | string | Yes | |
original.source | object | Yes | |
original.source.documentId | string | Yes | Minimum length: 1. |
original.source.cid | string | Yes | Minimum length: 1. |
lines | array | No | Items: object. Maximum items: 500. |
lines[].index | integer | Yes | Minimum: 0. |
lines[].description | string | Yes | Minimum length: 1. |
lines[].amountMinor | string | Yes | Pattern: "^[0-9]+$". |
totalMinor | string | No | |
currency | string | No | |
preview | object | No | |
preview.occurrenceIds | array | Yes | Items: string. Maximum items: 1. |
preview.repeated | boolean | Yes | Must be false. |
preview.postings | array | Yes | Items: object. |
preview.postings[].ledgerId | string | Yes | |
preview.postings[].accountCode | integer | Yes | |
preview.postings[].direction | string | Yes | Choose "debit", "credit". |
preview.postings[].amount | string | Yes | Pattern: "^[0-9]+$". |
command | object | No | |
command.name | string | Yes | Must be "contracts.reverse_economics". |
command.input | object | Yes | |
command.input.contractId | string | Yes | Minimum length: 1. |
command.input.activityKey | string | Yes | Minimum length: 1. |
command.input.occurrenceId | string | Yes | Minimum length: 1. |
command.input.sourceFactId | string | Yes | Minimum length: 1. |
command.input.effectiveAt | string | Yes | Format: date-time. |
command.input.evidence | array | Yes | Items: object. Minimum items: 1. |
command.input.evidence[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
command.input.evidence[].ref | string | Yes | Minimum length: 1. |
command.input.evidence[].signer | string | No | Minimum length: 1. |
command.input.refundSettled | boolean | No | Must be true. |
command.input.recognitionOnly | boolean | No | Must be true. |
command.source_document_id | string | Yes | |
command.effective_at | string | Yes | Format: date-time. |
command.idempotency_key | string | Yes |
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": "ingestions.credit_proposal"
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"ingestionId",
"creditText",
"expenseTargets"
],
"properties": {
"ingestionId": {
"type": "string"
},
"creditText": {
"type": "string"
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
}
}
}
},
"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",
"additionalProperties": false,
"required": [
"disposition",
"source",
"missing"
],
"allOf": [
{
"if": {
"properties": {
"disposition": {
"const": "ready"
}
}
},
"then": {
"required": [
"original",
"lines",
"totalMinor",
"currency",
"preview",
"command"
]
}
}
],
"properties": {
"disposition": {
"enum": [
"ready",
"needs_information"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"required": [
"documentId",
"cid",
"format",
"provenance",
"textCid",
"location"
],
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
},
"textCid": {
"type": "string"
},
"location": {
"type": "object",
"additionalProperties": false,
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 0
}
}
}
}
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"original": {
"type": "object",
"additionalProperties": false,
"required": [
"occurrenceId",
"documentId",
"cid",
"sourceFactId",
"contractId",
"activityKey",
"contractDocumentId",
"source"
],
"properties": {
"occurrenceId": {
"type": "string"
},
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"sourceFactId": {
"type": "string"
},
"contractId": {
"type": "string"
},
"activityKey": {
"type": "string"
},
"contractDocumentId": {
"type": "string"
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentId",
"cid"
]
}
}
},
"lines": {
"type": "array",
"maxItems": 500,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"description": {
"type": "string",
"minLength": 1
},
"amountMinor": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"required": [
"index",
"description",
"amountMinor"
]
}
},
"totalMinor": {
"type": "string"
},
"currency": {
"type": "string"
},
"preview": {
"type": "object",
"additionalProperties": false,
"required": [
"occurrenceIds",
"repeated",
"postings"
],
"properties": {
"occurrenceIds": {
"type": "array",
"maxItems": 1,
"items": {
"type": "string"
}
},
"repeated": {
"const": false
},
"postings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"ledgerId",
"accountCode",
"direction",
"amount"
],
"properties": {
"ledgerId": {
"type": "string"
},
"accountCode": {
"type": "integer"
},
"direction": {
"enum": [
"debit",
"credit"
]
},
"amount": {
"type": "string",
"pattern": "^[0-9]+$"
}
}
}
}
}
},
"command": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"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
}
}
},
"source_document_id": {
"type": "string"
},
"effective_at": {
"type": "string",
"format": "date-time"
},
"idempotency_key": {
"type": "string"
}
}
}
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}