payroll.record_statement

What it does

Record one evidenced provider invoice or payroll register atomically. Cost beneficiaries remain separate from actual creditors. Supply gross cost lines, the work month when known and business-owned expense classification. Omit liabilities only when the whole bill is owed to the provider on 2110; otherwise state net wages/withholding/employer liabilities explicitly. Never add employee deductions to gross costs. Funding, cash movement and refunds use independent payments, not new payroll expense.

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 payroll.record_statement 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.

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

See the exact schema below for the accepted shape.

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": "payroll.record_statement"
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "statementId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "providerPartyId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "sourceFactId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "reference": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "currency": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        },
        "total": {
          "type": "string",
          "pattern": "^(0|[1-9][0-9]*)$",
          "maxLength": 72
        },
        "invoiceDate": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "payrollDate": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "dueDate": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "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
              }
            }
          }
        },
        "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"
                  }
                }
              }
            }
          }
        },
        "lines": {
          "type": "array",
          "minItems": 1,
          "maxItems": 200,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "lineKey": {
                "type": "string",
                "minLength": 1,
                "maxLength": 512
              },
              "kind": {
                "enum": [
                  "pay",
                  "bonus",
                  "commission",
                  "employer_tax",
                  "benefits",
                  "reimbursement",
                  "fee",
                  "other"
                ]
              },
              "personPartyId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 512
              },
              "amount": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$",
                "maxLength": 72
              },
              "month": {
                "type": "string",
                "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
              },
              "providerConversion": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "currency": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  },
                  "amount": {
                    "type": "string",
                    "pattern": "^(0|[1-9][0-9]*)$",
                    "maxLength": 72
                  },
                  "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"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "required": [
                  "currency",
                  "amount"
                ]
              },
              "performancePeriod": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "from": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "through": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  }
                },
                "required": [
                  "from",
                  "through"
                ]
              },
              "approvedAt": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "approvalEvidence": {
                "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
                    }
                  }
                }
              },
              "expenseAccount": {
                "type": "integer"
              },
              "expenseFunction": {
                "enum": [
                  "cost_of_revenue",
                  "research_and_development",
                  "sales_and_marketing",
                  "general_and_administrative",
                  "other"
                ]
              }
            },
            "required": [
              "lineKey",
              "kind",
              "amount",
              "expenseAccount",
              "expenseFunction"
            ]
          }
        },
        "liabilities": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "partyId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 512
              },
              "accountCode": {
                "enum": [
                  2110,
                  2170,
                  2171,
                  2172
                ]
              },
              "amount": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]*)$",
                "maxLength": 72
              }
            },
            "required": [
              "partyId",
              "accountCode",
              "amount"
            ]
          }
        }
      },
      "required": [
        "statementId",
        "providerPartyId",
        "sourceFactId",
        "currency",
        "total",
        "lines",
        "evidence"
      ]
    },
    "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",
      "additionalProperties": true
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}

Example request

{
  "name": "payroll.record_statement",
  "input": {
    "statementId": "payroll_example",
    "providerPartyId": "pty_provider",
    "sourceFactId": "provider:invoice:1",
    "currency": "USD",
    "total": "10000",
    "lines": [
      {
        "lineKey": "salary",
        "kind": "pay",
        "personPartyId": "pty_person",
        "amount": "10000",
        "month": "2026-10",
        "expenseAccount": 5140,
        "expenseFunction": "research_and_development"
      }
    ],
    "evidence": [
      {
        "kind": "other",
        "ref": "synthetic-invoice"
      }
    ]
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "payroll.record_statement-example-0"
}