# ingestions.receipt_proposal Prepare a bill-and-payment proposal from a complete, evidenced vendor receipt. Requires a matching existing funding account, or a person's own card in the company's currency, and same-time full payment; incomplete receipts, fees and other FX need review. Does not post the proposal. ## What it does Prepare a manual ordinary receipts.record command from exact complete retained vendor_receipt JSON or PDF/text extraction with frozen receipt-fields-v1 or receipt-spans-v1 source selections, classified receipt. Source invoice fields: vendor,buyer,externalId,currency,effectiveAt,total,lines:[{description,amount}],optional zero tax/facts. Required payment:{status:'paid',externalId,last4:four digits}. Select existing current-priced vendor activity and financialAccountId; source last4 must uniquely match an active account in that currency, or a person's own card (ownerPartyId) in the company's currency, whose payment of the foreign receipt is recorded at the bill's booking rate (the preview shows the recorded currency and amount). Buyer must match this business. All source lines and exact total, current contract price, completed payment and ordinary funding checks apply. No service recognition, legal acceptance, payment initiation, fees, other FX or existing-bill settlement. Result is transient, manual, with original provenance; no durable receipt/proposal revision or financial write. Inline text remains unverified. Execute the returned ordinary command separately with current write authority; registered structured or supported complete source-bound PDF/UTF-8 receipt auto_record instead uses ingestions.start with an explicit frozen fundingAccounts policy and the existing delegated recording runner. Incomplete/unsupported PDF extraction, image originals, unverified inline automatic sources and existing-bill settlement remain review work. Payment never establishes service delivery. ## 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.receipt_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 | | | `receiptText` | 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`. | | `financialAccountId` | string | Yes | | ## 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"`. | | `missing` | array | Yes | Items: string. | | `source` | object | Yes | | | `source.documentId` | string | Yes | | | `source.cid` | string | Yes | | | `source.textCid` | string | Yes | | | `source.provenance` | string | Yes | Choose `"registered_bytes"`, `"caller_supplied_unverified"`. | | `billing` | object | No | | | `preview` | object | No | | | `command` | object | No | | | `command.name` | string | Yes | Must be `"receipts.record"`. | | `command.source_document_id` | string | Yes | | | `command.effective_at` | string | Yes | Format: date-time. | | `command.idempotency_key` | string | Yes | | | `command.input` | object | Yes | | | `command.input.processing` | object | No | | | `command.input.processing.rail` | string | Yes | Choose `"ach"`, `"ach_same_day"`, `"fedwire"`, `"rtp"`, `"sepa"`, `"sepa_instant"`, `"swift"`, `"onchain"`, `"internal"`, `"card"`. | | `command.input.processing.netAmount` | string | Yes | Pattern: `"^(0\|-?[1-9][0-9]*)$"`. | | `command.input.processing.feeFacts` | object | No | | | `command.input.processing.evidence` | array | Yes | Items: object. Minimum items: `1`. Maximum items: `20`. | | `command.input.processing.evidence[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.processing.evidence[].ref` | string | Yes | Minimum length: `1`. | | `command.input.processing.evidence[].signer` | string | No | Minimum length: `1`. | | `command.input.billing` | object | Yes | Choose a matching alternative in the exact schema below. | | `command.input.billing.contractId` | string | Yes | Minimum length: `1`. | | `command.input.billing.activityKey` | string | Yes | Minimum length: `1`. | | `command.input.billing.occurrenceKey` | string | Yes | Minimum length: `1`. | | `command.input.billing.obligationKey` | string | No | Minimum length: `1`. | | `command.input.billing.sourceFactId` | string | Yes | Minimum length: `1`. | | `command.input.billing.effectiveAt` | string | Yes | Format: date-time. | | `command.input.billing.phase` | string | Yes | Must be `"billing"`. | | `command.input.billing.dueDate` | string | No | Format: date. | | `command.input.billing.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. | | `command.input.billing.exchangeRate.base` | string | Yes | Pattern: `"^[A-Z]{3}$"`. | | `command.input.billing.exchangeRate.quote` | string | Yes | Pattern: `"^[A-Z]{3}$"`. | | `command.input.billing.exchangeRate.date` | string | Yes | Format: date. | | `command.input.billing.exchangeRate.numerator` | string | Yes | Pattern: `"^[1-9][0-9]*$"`. | | `command.input.billing.exchangeRate.denominator` | string | Yes | Pattern: `"^[1-9][0-9]*$"`. | | `command.input.billing.exchangeRate.evidence` | array | Yes | Items: object. Minimum items: `1`. | | `command.input.billing.exchangeRate.evidence[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.billing.exchangeRate.evidence[].ref` | string | Yes | Minimum length: `1`. | | `command.input.billing.exchangeRate.evidence[].signer` | string | No | | | `command.input.billing.period` | object | No | | | `command.input.billing.period.from` | string | Yes | Format: date-time. | | `command.input.billing.period.through` | string | Yes | Format: date-time. | | `command.input.billing.facts` | object | No | | | `command.input.billing.evidence` | object | No | | | `command.input.billing.evidence.billing` | array | No | Items: object. Minimum items: `1`. Maximum items: `20`. | | `command.input.billing.evidence.billing[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.billing.evidence.billing[].ref` | string | Yes | Minimum length: `1`. | | `command.input.billing.evidence.billing[].signer` | string | No | Minimum length: `1`. | | `command.input.billing.evidence.service` | array | No | Items: object. Minimum items: `1`. Maximum items: `20`. | | `command.input.billing.evidence.service[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.billing.evidence.service[].ref` | string | Yes | Minimum length: `1`. | | `command.input.billing.evidence.service[].signer` | string | No | Minimum length: `1`. | | `command.input.billing.evidence.acceptance` | array | No | Items: object. Minimum items: `1`. Maximum items: `20`. | | `command.input.billing.evidence.acceptance[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.billing.evidence.acceptance[].ref` | string | Yes | Minimum length: `1`. | | `command.input.billing.evidence.acceptance[].signer` | string | No | Minimum length: `1`. | | `command.input.billing.evidence.economic` | array | No | Items: object. Minimum items: `1`. Maximum items: `20`. | | `command.input.billing.evidence.economic[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.billing.evidence.economic[].ref` | string | Yes | Minimum length: `1`. | | `command.input.billing.evidence.economic[].signer` | string | No | Minimum length: `1`. | | `command.input.payment` | object | Yes | | | `command.input.payment.financialAccountId` | string | Yes | Minimum length: `1`. | | `command.input.payment.direction` | string | Yes | Choose `"in"`, `"out"`. | | `command.input.payment.amount` | string | Yes | Pattern: `"^[1-9][0-9]*$"`. | | `command.input.payment.currency` | string | Yes | Minimum length: `1`. | | `command.input.payment.partyId` | string | Yes | Minimum length: `1`. | | `command.input.payment.effectiveAt` | string | Yes | Format: date-time. | | `command.input.payment.sourceFactId` | string | Yes | Minimum length: `1`. | | `command.input.payment.evidence` | array | Yes | Items: object. Minimum items: `1`. Maximum items: `20`. | | `command.input.payment.evidence[].kind` | string | Yes | Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. | | `command.input.payment.evidence[].ref` | string | Yes | Minimum length: `1`. | | `command.input.payment.evidence[].signer` | string | No | Minimum length: `1`. | [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.receipt_proposal" }, "input": { "type": "object", "additionalProperties": false, "required": [ "ingestionId", "receiptText", "expenseTargets", "financialAccountId" ], "properties": { "ingestionId": { "type": "string" }, "receiptText": { "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" ] } }, "financialAccountId": { "type": "string" } } }, "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", "required": [ "disposition", "source", "missing" ], "properties": { "disposition": { "enum": [ "ready", "needs_information" ] }, "missing": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "required": [ "documentId", "cid", "textCid", "provenance" ], "properties": { "documentId": { "type": "string" }, "cid": { "type": "string" }, "textCid": { "type": "string" }, "provenance": { "enum": [ "registered_bytes", "caller_supplied_unverified" ] } } }, "billing": { "type": "object" }, "preview": { "type": "object" }, "command": { "type": "object", "required": [ "name", "source_document_id", "effective_at", "idempotency_key", "input" ], "properties": { "name": { "const": "receipts.record" }, "source_document_id": { "type": "string" }, "effective_at": { "type": "string", "format": "date-time" }, "idempotency_key": { "type": "string" }, "input": { "type": "object", "additionalProperties": false, "required": [ "billing", "payment" ], "properties": { "processing": { "type": "object", "additionalProperties": false, "required": [ "rail", "netAmount", "evidence" ], "properties": { "rail": { "enum": [ "ach", "ach_same_day", "fedwire", "rtp", "sepa", "sepa_instant", "swift", "onchain", "internal", "card" ] }, "netAmount": { "type": "string", "pattern": "^(0|-?[1-9][0-9]*)$" }, "feeFacts": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } }, "evidence": { "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 } } } } } }, "billing": { "type": "object", "additionalProperties": false, "required": [ "contractId", "activityKey", "occurrenceKey", "sourceFactId", "effectiveAt", "phase" ], "anyOf": [ { "type": "object", "properties": { "obligationKey": { "type": "string", "minLength": 1 } }, "required": [ "obligationKey" ] }, { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "through": { "type": "string", "minLength": 1 } }, "required": [ "from", "through" ] } }, "required": [ "period" ] } ], "properties": { "contractId": { "type": "string", "minLength": 1 }, "activityKey": { "type": "string", "minLength": 1 }, "occurrenceKey": { "type": "string", "minLength": 1 }, "obligationKey": { "type": "string", "minLength": 1 }, "sourceFactId": { "type": "string", "minLength": 1 }, "effectiveAt": { "type": "string", "format": "date-time" }, "phase": { "const": "billing" }, "dueDate": { "type": "string", "format": "date" }, "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" } } } } } }, "period": { "type": "object", "additionalProperties": false, "required": [ "from", "through" ], "properties": { "from": { "type": "string", "format": "date-time" }, "through": { "type": "string", "format": "date-time" } } }, "facts": { "type": "object", "maxProperties": 100, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "required": [ "occurrenceId" ], "properties": { "occurrenceId": { "type": "string", "minLength": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "claimId", "component" ], "properties": { "claimId": { "type": "string", "minLength": 1 }, "component": { "type": "object", "additionalProperties": false, "required": [ "originLedgerId", "accountCode" ], "properties": { "originLedgerId": { "type": "string", "minLength": 1 }, "accountCode": { "type": "integer" } } } } } ] } }, "evidence": { "type": "object", "additionalProperties": false, "properties": { "billing": { "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 } } } }, "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 } } } } } } } }, "payment": { "type": "object", "additionalProperties": false, "required": [ "financialAccountId", "direction", "amount", "currency", "partyId", "effectiveAt", "sourceFactId", "evidence" ], "properties": { "financialAccountId": { "type": "string", "minLength": 1 }, "direction": { "enum": [ "in", "out" ] }, "amount": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "currency": { "type": "string", "minLength": 1 }, "partyId": { "type": "string", "minLength": 1 }, "effectiveAt": { "type": "string", "format": "date-time" }, "sourceFactId": { "type": "string", "minLength": 1 }, "evidence": { "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 } } } } } } } } } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "cid": { "type": "string" } } } } } } ```