# receipts.record

Record one evidenced bill and its full same-time payment together. Use for a paid purchase, not settlement of an existing bill; does not send a payment.

## What it does

Atomically record one priced-right commercial billing and its full same-time payment. Supply billing facts/evidence and separate payment facts/evidence. Amount must equal the gross calculated claim, including tax. A payment from a person's own card or account (ownerPartyId) of a bill in another currency is stated in the bill's currency and recorded in the account's at the bill's booking rate. Emits separate economics and payment events without recognizing delivery or revenue/expense. Retries use the same idempotency key; existing bills use payments.record.

Optional processing adds the account provider service fee with explicit rail, net amount and usage evidence; no arbitrary batch.

## 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 `receipts.record` 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 |
|---|---|---|---|
| `processing` | object | No |   |
| `processing.rail` | string | Yes |  Choose `"ach"`, `"ach_same_day"`, `"fedwire"`, `"rtp"`, `"sepa"`, `"sepa_instant"`, `"swift"`, `"onchain"`, `"internal"`, `"card"`. |
| `processing.netAmount` | string | Yes |  Pattern: `"^(0\|-?[1-9][0-9]*)$"`. |
| `processing.feeFacts` | object | No |   |
| `processing.evidence` | array | Yes |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `processing.evidence[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `processing.evidence[].ref` | string | Yes |  Minimum length: `1`. |
| `processing.evidence[].signer` | string | No |  Minimum length: `1`. |
| `billing` | object | Yes |  Choose a matching alternative in the exact schema below. |
| `billing.contractId` | string | Yes |  Minimum length: `1`. |
| `billing.activityKey` | string | Yes |  Minimum length: `1`. |
| `billing.occurrenceKey` | string | Yes |  Minimum length: `1`. |
| `billing.obligationKey` | string | No |  Minimum length: `1`. |
| `billing.sourceFactId` | string | Yes |  Minimum length: `1`. |
| `billing.effectiveAt` | string | Yes |  Format: date-time. |
| `billing.phase` | string | Yes |  Must be `"billing"`. |
| `billing.dueDate` | string | No |  Format: date. |
| `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.  |
| `billing.exchangeRate.base` | string | Yes |  Pattern: `"^[A-Z]{3}$"`. |
| `billing.exchangeRate.quote` | string | Yes |  Pattern: `"^[A-Z]{3}$"`. |
| `billing.exchangeRate.date` | string | Yes |  Format: date. |
| `billing.exchangeRate.numerator` | string | Yes |  Pattern: `"^[1-9][0-9]*$"`. |
| `billing.exchangeRate.denominator` | string | Yes |  Pattern: `"^[1-9][0-9]*$"`. |
| `billing.exchangeRate.evidence` | array | Yes |  Items: object. Minimum items: `1`. |
| `billing.exchangeRate.evidence[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `billing.exchangeRate.evidence[].ref` | string | Yes |  Minimum length: `1`. |
| `billing.exchangeRate.evidence[].signer` | string | No |   |
| `billing.period` | object | No |   |
| `billing.period.from` | string | Yes |  Format: date-time. |
| `billing.period.through` | string | Yes |  Format: date-time. |
| `billing.facts` | object | No |   |
| `billing.evidence` | object | No |   |
| `billing.evidence.billing` | array | No |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `billing.evidence.billing[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `billing.evidence.billing[].ref` | string | Yes |  Minimum length: `1`. |
| `billing.evidence.billing[].signer` | string | No |  Minimum length: `1`. |
| `billing.evidence.service` | array | No |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `billing.evidence.service[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `billing.evidence.service[].ref` | string | Yes |  Minimum length: `1`. |
| `billing.evidence.service[].signer` | string | No |  Minimum length: `1`. |
| `billing.evidence.acceptance` | array | No |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `billing.evidence.acceptance[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `billing.evidence.acceptance[].ref` | string | Yes |  Minimum length: `1`. |
| `billing.evidence.acceptance[].signer` | string | No |  Minimum length: `1`. |
| `billing.evidence.economic` | array | No |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `billing.evidence.economic[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `billing.evidence.economic[].ref` | string | Yes |  Minimum length: `1`. |
| `billing.evidence.economic[].signer` | string | No |  Minimum length: `1`. |
| `payment` | object | Yes |   |
| `payment.financialAccountId` | string | Yes |  Minimum length: `1`. |
| `payment.direction` | string | Yes |  Choose `"in"`, `"out"`. |
| `payment.amount` | string | Yes |  Pattern: `"^[1-9][0-9]*$"`. |
| `payment.currency` | string | Yes |  Minimum length: `1`. |
| `payment.partyId` | string | Yes |  Minimum length: `1`. |
| `payment.effectiveAt` | string | Yes |  Format: date-time. |
| `payment.sourceFactId` | string | Yes |  Minimum length: `1`. |
| `payment.evidence` | array | Yes |  Items: object. Minimum items: `1`. Maximum items: `20`. |
| `payment.evidence[].kind` | string | Yes |  Choose `"tap_message"`, `"x402_receipt"`, `"chain_tx"`, `"signed_doc"`, `"stripe_object"`, `"other"`. |
| `payment.evidence[].ref` | string | Yes |  Minimum length: `1`. |
| `payment.evidence[].signer` | string | No |  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 |
|---|---|---|---|
| `economic` | object | Yes |   |
| `payment` | object | Yes |   |
| `processing` | object | No |   |


[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": "receipts.record"
    },
    "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "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",
      "required": [
        "economic",
        "payment"
      ],
      "properties": {
        "economic": {
          "type": "object"
        },
        "payment": {
          "type": "object"
        },
        "processing": {
          "type": "object"
        }
      }
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}
```