journal.post

Record an explicitly supplied, evidenced journal whose postings balance within each ledger. Prefer the relevant business command for ordinary invoices, bills and payments.

What it does

Post a balanced journal in the business’s functional currency for its effective date, or in a token’s CAIP-19 for a wallet’s token movement, in the token’s smallest unit and its own ledger. An entry dated before a functional-currency change is recorded in the current ledger at the frozen change rate, effective when that ledger opened, with the original lines kept as evidence. Use decimal integer strings for amounts; corrections use journal.void.

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 journal.post 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.

Field	Type	Required	Meaning and accepted values
`description`	string	Yes	Maximum length: `1024`. Example: `"Founder contributed inventory"`.
`currency`	string	Yes	The functional currency, or a token’s CAIP-19 for a wallet’s token movement: amounts are then in the token’s smallest unit and post in its own ledger. Example: `"USD"`.
`decimals`	integer	No	Optional precision read from the token contract for its first movement. When omitted for an unlisted ERC-20 token, the control plane reads it through ValidationCloud on a configured chain. Kept on the token’s ledger; a later entry may omit it. Minimum: `0`. Maximum: `18`.
`externalRef`	string	No	Maximum length: `200`.
`stripeFeeTransactionId`	string	No	Stripe balance transaction for a standalone fee. Requires its hashed stripe-funds externalRef. An existing fee source leaves the books unchanged; raw provider identity stays in the private command receipt, not the journal event.
`lines`	array	Yes	Items: object. Minimum items: `2`. Maximum items: `100`.
`lines[].accountCode`	integer	Yes	Example: `1140`.
`lines[].direction`	string	Yes	Choose `"debit"`, `"credit"`. Example: `"debit"`.
`lines[].amount`	string	Yes	Pattern: `"^(0\|[1-9][0-9]*)$"`. Example: `"10000"`.
`lines[].subKey`	object	No
`lines[].subKey.kind`	number	No	Choose `0`, `1`, `2`, `3`, `4`, `5`, `6`.
`lines[].subKey.symbol`	string	No
`lines[].subKey.partyId`	string	No
`lines[].subKey.sku`	string	No
`lines[].subKey.financialAccountId`	string	No
`lines[].subKey.taxCodeId`	string	No
`lines[].subKey.expenseFunction`	string	No	Choose `"cost_of_revenue"`, `"research_and_development"`, `"sales_and_marketing"`, `"general_and_administrative"`, `"other"`.
`lines[].asset`	string	No
`lines[].assetAmount`	string	No
`lines[].externalId`	string	No	Maximum length: `200`.

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
`eventId`	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": "journal.post"
    },
    "input": {
      "type": "object",
      "required": [
        "description",
        "currency",
        "lines"
      ],
      "properties": {
        "description": {
          "type": "string",
          "maxLength": 1024
        },
        "currency": {
          "type": "string",
          "description": "The functional currency, or a token's CAIP-19 for a wallet's token movement: amounts are then in the token's smallest unit and post in its own ledger.",
          "examples": [
            "USD",
            "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
          ]
        },
        "decimals": {
          "type": "integer",
          "minimum": 0,
          "maximum": 18,
          "description": "Optional precision read from the token contract for its first movement. When omitted for an unlisted ERC-20 token, the control plane reads it through ValidationCloud on a configured chain. Kept on the token's ledger; a later entry may omit it."
        },
        "externalRef": {
          "type": "string",
          "maxLength": 200
        },
        "stripeFeeTransactionId": {
          "type": "string",
          "description": "Stripe balance transaction for a standalone fee. Requires its hashed stripe-funds externalRef. An existing fee source leaves the books unchanged; raw provider identity stays in the private command receipt, not the journal event."
        },
        "lines": {
          "type": "array",
          "minItems": 2,
          "maxItems": 100,
          "items": {
            "type": "object",
            "required": [
              "accountCode",
              "direction",
              "amount"
            ],
            "properties": {
              "accountCode": {
                "type": "integer"
              },
              "direction": {
                "enum": [
                  "debit",
                  "credit"
                ]
              },
              "amount": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$"
              },
              "subKey": {
                "type": "object",
                "properties": {
                  "kind": {
                    "enum": [
                      0,
                      1,
                      2,
                      3,
                      4,
                      5,
                      6
                    ]
                  },
                  "symbol": {
                    "type": "string"
                  },
                  "partyId": {
                    "type": "string"
                  },
                  "sku": {
                    "type": "string"
                  },
                  "financialAccountId": {
                    "type": "string"
                  },
                  "taxCodeId": {
                    "type": "string"
                  },
                  "expenseFunction": {
                    "enum": [
                      "cost_of_revenue",
                      "research_and_development",
                      "sales_and_marketing",
                      "general_and_administrative",
                      "other"
                    ]
                  }
                }
              },
              "asset": {
                "type": "string"
              },
              "assetAmount": {
                "type": "string"
              },
              "externalId": {
                "type": "string",
                "maxLength": 200
              }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "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": [
        "eventId"
      ],
      "properties": {
        "eventId": {
          "type": "integer"
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}

Example request

{
  "name": "journal.post",
  "input": {
    "description": "Founder contributed inventory",
    "currency": "USD",
    "lines": [
      {
        "accountCode": 1140,
        "direction": "debit",
        "amount": "10000"
      },
      {
        "accountCode": 3100,
        "direction": "credit",
        "amount": "10000"
      }
    ]
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "journal.post-example-0"
}