# ingestions.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](/docs/api/) 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](/docs/command-reference/) · [Operation and errors](/docs/api-reference/operations/commands-execute/) · [Reusable schemas](/docs/api-reference/components/)

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

## Exact request schema


```json
{
  "$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


```json
{
  "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"
          }
        }
      }
    }
  }
}
```