# 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](/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 |
|---|---|---|---|
| `statementId` | string | Yes |  Minimum length: `1`. Maximum length: `512`. Example: `"payroll_example"`. |
| `providerPartyId` | string | Yes |  Minimum length: `1`. Maximum length: `512`. Example: `"pty_provider"`. |
| `sourceFactId` | string | Yes |  Minimum length: `1`. Maximum length: `512`. Example: `"provider:invoice:1"`. |
| `reference` | string | No |  Minimum length: `1`. Maximum length: `512`. |
| `currency` | string | Yes |  Minimum length: `1`. Maximum length: `512`. Example: `"USD"`. |
| `total` | string | Yes |  Maximum length: `72`. Pattern: `"^(0\|[1-9][0-9]*)$"`. Example: `"10000"`. |
| `invoiceDate` | string | No |  Pattern: `"^\\d{4}-\\d{2}-\\d{2}$"`. |
| `payrollDate` | string | No |  Pattern: `"^\\d{4}-\\d{2}-\\d{2}$"`. |
| `dueDate` | string | No |  Pattern: `"^\\d{4}-\\d{2}-\\d{2}$"`. |
| `evidence` | array | Yes |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `evidence[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. Example: `"other"`. |
| `evidence[].ref` | string | Yes |  Minimum length: `1`. Example: `"synthetic-invoice"`. |
| `evidence[].signer` | 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 |   |
| `lines` | array | Yes |  Items: object. Minimum items: `1`. Maximum items: `200`. |
| `lines[].lineKey` | string | Yes |  Minimum length: `1`. Maximum length: `512`. Example: `"salary"`. |
| `lines[].kind` | string | Yes |  Choose `"pay"`, `"bonus"`, `"commission"`, `"employer_tax"`, `"benefits"`, `"reimbursement"`, `"fee"`, `"other"`. Example: `"pay"`. |
| `lines[].personPartyId` | string | No |  Minimum length: `1`. Maximum length: `512`. Example: `"pty_person"`. |
| `lines[].amount` | string | Yes |  Maximum length: `72`. Pattern: `"^(0\|[1-9][0-9]*)$"`. Example: `"10000"`. |
| `lines[].month` | string | No |  Pattern: `"^\\d{4}-(0[1-9]\|1[0-2])$"`. Example: `"2026-10"`. |
| `lines[].providerConversion` | object | No |   |
| `lines[].providerConversion.currency` | string | Yes |  Minimum length: `1`. Maximum length: `512`. |
| `lines[].providerConversion.amount` | string | Yes |  Maximum length: `72`. Pattern: `"^(0\|[1-9][0-9]*)$"`. |
| `lines[].providerConversion.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.  |
| `lines[].providerConversion.exchangeRate.base` | string | Yes |  Pattern: `"^[A-Z]{3}$"`. |
| `lines[].providerConversion.exchangeRate.quote` | string | Yes |  Pattern: `"^[A-Z]{3}$"`. |
| `lines[].providerConversion.exchangeRate.date` | string | Yes |  Format: date. |
| `lines[].providerConversion.exchangeRate.numerator` | string | Yes |  Pattern: `"^[1-9][0-9]*$"`. |
| `lines[].providerConversion.exchangeRate.denominator` | string | Yes |  Pattern: `"^[1-9][0-9]*$"`. |
| `lines[].providerConversion.exchangeRate.evidence` | array | Yes |  Items: object. Minimum items: `1`. |
| `lines[].providerConversion.exchangeRate.evidence[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `lines[].providerConversion.exchangeRate.evidence[].ref` | string | Yes |  Minimum length: `1`. |
| `lines[].providerConversion.exchangeRate.evidence[].signer` | string | No |   |
| `lines[].performancePeriod` | object | No |   |
| `lines[].performancePeriod.from` | string | Yes |  Pattern: `"^\\d{4}-\\d{2}-\\d{2}$"`. |
| `lines[].performancePeriod.through` | string | Yes |  Pattern: `"^\\d{4}-\\d{2}-\\d{2}$"`. |
| `lines[].approvedAt` | string | No |  Pattern: `"^\\d{4}-\\d{2}-\\d{2}$"`. |
| `lines[].approvalEvidence` | array | No |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `lines[].approvalEvidence[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `lines[].approvalEvidence[].ref` | string | Yes |  Minimum length: `1`. |
| `lines[].approvalEvidence[].signer` | string | No |  Minimum length: `1`. |
| `lines[].expenseAccount` | integer | Yes |  Example: `5140`. |
| `lines[].expenseFunction` | string | Yes |  Choose `"cost_of_revenue"`, `"research_and_development"`, `"sales_and_marketing"`, `"general_and_administrative"`, `"other"`. Example: `"research_and_development"`. |
| `liabilities` | array | No |  Items: object. Minimum items: `1`. Maximum items: `100`. |
| `liabilities[].partyId` | string | Yes |  Minimum length: `1`. Maximum length: `512`. |
| `liabilities[].accountCode` | number | Yes |  Choose `2110`, `2170`, `2171`, `2172`. |
| `liabilities[].amount` | string | Yes |  Maximum length: `72`. Pattern: `"^(0\|[1-9][0-9]*)$"`. |

## 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](/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": "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


```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": true
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

## Example request


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