Economicocontracts.record
Record an evidenced activity or priced-right phase against an existing contract. Read the contract first for its facts and allowed phases. Billing, delivery, recognition and payment are distinct; no invoice is sent or money moved.
What it does
Record one bound right or legacy activity with named observed facts and evidence. For quantity adjustment billing, taxAmount states invoice tax separately from invoicedAmount; supplier tax uses the stated figure and differences raise tax_differs attention. For priced-rights contracts, phase separates billing, delivery/usage and recognition; period identifies coverage, or obligationKey identifies a one-off obligation.
A declared profit_allocation period rule allocates evidenced retained profit (default) or loss (result: loss) to an established member at the final instant of its completed period, with no cash or new claim. Select consequenceKey when multiple period rules match. A declared close_draws ownership period rule reclassifies accumulated holder draws into capital with completeThrough and acceptance/economic evidence, without cash or a claim.
Declared minimum rules use period_close with economic/service evidence and completeThrough; they reconcile only the shortfall after eligible billing and recognition, and lock that coverage against late uncorrected facts. Billing requires billing evidence and may carry an explicit dueDate (YYYY-MM-DD); omitted dates remain unknown.
A service right priced in a currency other than the functional one keeps its claim, tax, unbilled receivable and accrued expense in its own currency’s ledger and books its revenue or expense, prepaid expense and deferred revenue in the functional ledger at the obligation’s first booking date’s rate, frozen in the event, each ledger balanced through 3420 Currency exchange; the rate comes from the shared rate store, or from an evidenced exchangeRate you state. Delivery/recognition requires service evidence, and funding fields are refused.
For a billed delivery-based service, serviceShare records one of count equal shares (index 1..count); the last share takes rounding and all shares keep the billed price, bound to billingOccurrenceId. A declared output/input/reverse-charge/imported-services tax code derives tax at billing from the before-tax price using its in-force rate; recognition never rebills tax. A declared convert_claim exercise atomically turns an identified payable into the same holder’s equity using economic evidence, optionally issuing declared restricted or unrestricted units from the available authorized pool.
A declared issue_units exercise with money consideration creates an investment receivable, explicit capital and authorized units, without an invoice or payment; when the right is explicitly priced at exactly zero and the consideration matches (a member’s units issued for no capital), it issues only the units, with no claim or monetary posting. A vendor right’s declared reduction takes its dated percentage or amount off by service date, booking gross expense and the reduction as contra-expense 5950; facts.reductionAmount states the invoice’s own discount.
A lot right’s billing buys a credit lot from its receipt, and its exercise grants a vendor’s credit (acceptance evidence) or, with consequenceKey expire, lapses one (economic evidence); a credit pool’s eligible rights draw their lots in the pool’s order at billing or recognition, facts.creditApplied stating the invoice’s credit, and terminating the contract refunds or retires what is left and makes overflow the pool still accrues a payable to the vendor. The frozen definition computes outcomes; callers cannot provide postings.
Source fact identity is business-wide; identical occurrences do not post twice. Legacy corrections explicitly reference the latest active recorded occurrence and preserve its history; activity_effects previews legacy activities only.
For a received billing, invoiceReference retains the vendor invoice number separately from sourceFactId; disjoint service periods may share it. replacesBillId explicitly names an old ordinary occurrenceId or usage reconciliationId to reverse with all its lines before this new billing, atomically; give a fresh source fact, the same vendor party and currency, and a date at or after the reversed phases. Paid value remains as vendor credit and applies to the replacement bill; replacement in the result names any remaining credit.
Usage periods with later changes or credit-lot movements need their dependencies corrected first. Priced-right previews are not yet supported. An equal-price received bill on another right sharing the normalized invoice and overlapping coverage posts with invoice_overlap review attention; the business decides whether both charges stand. A period-less fee on the same received right as a period bill also posts and raises invoice_overlap when its effective date falls within the bill coverage, in either recording order.
The agent receives one pending item per right and bill period, with relatedOccurrenceId naming the other charge; further fees add no review events while it is held. Read usageReviewItems and attention.usageReview, then use contracts.resolve_usage_review to record the business decision. This period review remains pending after either charge is reversed because other fees may still overlap. Read required fact schemas from the contract subject.
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.record through GET /v1/catalog/commands/{name} before acting.
The envelope may reference a registered source document of kind source_document, activity_statement, contract; 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". |
activityKey | string | Yes | Minimum length: 1. Example: "work". |
occurrenceKey | string | Yes | Minimum length: 1. Example: "timesheet-1". |
sourceFactId | string | Yes | Minimum length: 1. Example: "timesheet:approved:1". |
invoiceReference | string | No | The vendor’s invoice number for received billing, separately from the recording’s source fact. Minimum length: 1. |
replacesBillId | string | No | Explicitly reverse this vendor occurrenceId or usage reconciliationId and record the new bill in the same transaction. Minimum length: 1. |
effectiveAt | string | Yes | Format: date-time. Minimum length: 1. Example: "2026-09-01T00:00:00Z". |
dueDate | string | No | Evidenced due date for a priced-right billing claim only; omit when unknown. Format: date. Minimum length: 1. |
facts | object | No | |
evidence | object | No | |
evidence.payment | array | No | Items: object. Maximum items: 20. |
evidence.payment[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
evidence.payment[].ref | string | Yes | Minimum length: 1. |
evidence.payment[].signer | string | No | Minimum length: 1. |
evidence.service | array | No | Items: object. Maximum items: 20. |
evidence.service[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". Example: "other". |
evidence.service[].ref | string | Yes | Minimum length: 1. Example: "timesheet:approved:1". |
evidence.service[].signer | string | No | Minimum length: 1. |
evidence.acceptance | array | No | Items: object. Maximum items: 20. |
evidence.acceptance[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
evidence.acceptance[].ref | string | Yes | Minimum length: 1. |
evidence.acceptance[].signer | string | No | Minimum length: 1. |
evidence.billing | array | No | Items: object. Maximum items: 20. |
evidence.billing[].kind | string | Yes | Choose "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other". |
evidence.billing[].ref | string | Yes | Minimum length: 1. |
evidence.billing[].signer | string | No | Minimum length: 1. |
evidence.economic | array | No | Items: object. 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. |
correctsOccurrenceId | string | No | Minimum length: 1. |
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 | |
paymentMethodId | string | No | Minimum length: 1. |
phase | string | No | Choose "billing", "delivery", "usage", "recognition", "exercise", "period_close". |
serviceShare | object | No | |
serviceShare.billingOccurrenceId | string | Yes | Minimum length: 1. |
serviceShare.index | integer | Yes | Minimum: 1. Maximum: 12. |
serviceShare.count | integer | Yes | Minimum: 1. Maximum: 12. |
adjustment | schema-defined | No | Choose a matching alternative in the exact schema below. |
invoicedAmount | string | No | Pattern: "^(0|[1-9][0-9]*)$". |
taxAmount | string | No | Pattern: "^(0|[1-9][0-9]*)$". |
consequenceKey | string | No | Minimum length: 1. |
obligationKey | string | No | Minimum length: 1. |
period | object | No | |
period.from | string | Yes | Format: date-time. Minimum length: 1. |
period.through | string | Yes | Format: date-time. 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 |
|---|---|---|---|
replacement | object | No | |
replacement.billId | string | No | Minimum length: 1. |
replacement.reversedPhases | array | No | Items: string. |
replacement.creditClaimId | string | No | Minimum length: 1. |
replacement.creditAmount | string | No | Minimum length: 1. |
replacement.appliedCredit | string | No | Minimum length: 1. |
replacement.remainingCredit | string | No | Minimum length: 1. |
occurrenceId | string | Yes | Minimum length: 1. |
documentId | string | Yes | Minimum length: 1. |
cid | string | Yes | Minimum length: 1. |
duplicate | boolean | Yes | |
evaluation | object | Yes | |
claimIds | array | No | Items: string. |
claims | array | No | Payment-ready claim identities returned for priced-right economic phases. Items: object. |
claims[].claimId | string | Yes | Minimum length: 1. |
claims[].component | object | Yes | |
claims[].component.originLedgerId | string | Yes | Minimum length: 1. |
claims[].component.accountCode | integer | 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": "contracts.record"
},
"input": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"invoiceReference": {
"type": "string",
"minLength": 1,
"description": "The vendor's invoice number for received billing, separately from the recording's source fact."
},
"replacesBillId": {
"type": "string",
"minLength": 1,
"description": "Explicitly reverse this vendor occurrenceId or usage reconciliationId and record the new bill in the same transaction."
},
"effectiveAt": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"dueDate": {
"type": "string",
"minLength": 1,
"format": "date",
"description": "Evidenced due date for a priced-right billing claim only; omit when unknown."
},
"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",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
}
}
}
}
]
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"payment": {
"type": "array",
"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",
"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",
"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": "array",
"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",
"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
}
}
}
}
}
},
"correctsOccurrenceId": {
"type": "string",
"minLength": 1
},
"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"
}
}
}
}
}
},
"paymentMethodId": {
"type": "string",
"minLength": 1
},
"phase": {
"enum": [
"billing",
"delivery",
"usage",
"recognition",
"exercise",
"period_close"
]
},
"serviceShare": {
"type": "object",
"additionalProperties": false,
"required": [
"index",
"count",
"billingOccurrenceId"
],
"properties": {
"billingOccurrenceId": {
"type": "string",
"minLength": 1
},
"index": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"count": {
"type": "integer",
"minimum": 1,
"maximum": 12
}
}
},
"adjustment": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"amendment": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"cid"
]
}
},
"required": [
"amendment"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"changeId": {
"type": "string",
"minLength": 1
}
},
"required": [
"changeId"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"trueUp": {
"type": "object",
"additionalProperties": false,
"properties": {
"from": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"through": {
"type": "string",
"minLength": 1,
"format": "date-time"
}
},
"required": [
"from",
"through"
]
}
},
"required": [
"trueUp"
]
}
]
},
"invoicedAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"taxAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"consequenceKey": {
"type": "string",
"minLength": 1
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"period": {
"type": "object",
"additionalProperties": false,
"required": [
"from",
"through"
],
"properties": {
"from": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"through": {
"type": "string",
"minLength": 1,
"format": "date-time"
}
}
}
},
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt"
]
},
"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, activity_statement, contract 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",
"properties": {
"replacement": {
"type": "object",
"properties": {
"billId": {
"type": "string",
"minLength": 1
},
"reversedPhases": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"creditClaimId": {
"type": "string",
"minLength": 1
},
"creditAmount": {
"type": "string",
"minLength": 1
},
"appliedCredit": {
"type": "string",
"minLength": 1
},
"remainingCredit": {
"type": "string",
"minLength": 1
}
}
},
"occurrenceId": {
"type": "string",
"minLength": 1
},
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
},
"duplicate": {
"type": "boolean"
},
"evaluation": {
"type": "object"
},
"claimIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claimId",
"component"
],
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"component": {
"type": "object",
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
}
},
"description": "Payment-ready claim identities returned for priced-right economic phases."
}
},
"required": [
"occurrenceId",
"documentId",
"cid",
"duplicate",
"evaluation"
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}Example request
{
"name": "contracts.record",
"input": {
"contractId": "ctr_example",
"activityKey": "work",
"occurrenceKey": "timesheet-1",
"sourceFactId": "timesheet:approved:1",
"effectiveAt": "2026-09-01T00:00:00Z",
"facts": {
"quantity": "12500000"
},
"evidence": {
"service": [
{
"kind": "other",
"ref": "timesheet:approved:1"
}
]
}
},
"effective_at": "2026-09-01T00:00:00Z",
"idempotency_key": "contracts.record-example-0"
}