Skip to content
Gestalt

API: Economy

Capability state: invoice/paymentObservation/bookkeepingFact are staging-durable; periodClose is fixture-rehearsed. See reference/capability-state.md.

The economy operations cover the invoice → payment → bookkeeping → period-close pipeline as a sequence of admitted atoms with closure surfaces and obligations between them. They are also composed by the vertical.de.invoicePaymentAdvisor vertical operation.

Pipeline shape

Section titled “Pipeline shape”
economy.invoice
   |
   |  emits: receivable obligation, closure surface
   v
economy.paymentObservation
   |
   |  emits: settlement (closes the receivable)
   v
economy.bookkeepingFact
   |
   |  requires: invoice + payment_observation + advisor_evidence
   v
economy.periodClose
   |
   |  requires: closure_clearance evidence; refuses if surfaces are open
   v
period closed atom

Each step is its own atom. Each atom emits its own receipt.

economy.invoice

Section titled “economy.invoice”

Create invoice economic state with receivable obligation and closure surface.

POST /v1/economy/invoice
state: staging-durable
sdk_role: create invoice economic state with receivable obligation and closure surface
request_record: CloudEconomicInvoiceRequest
responses: invoice | obligation | closure_surface | refusal | receipt

Request

Section titled “Request”
interface EconomicInvoiceRequest {
  tenant?: GestaltRef;
  invoice?: GestaltRef;       // optional pre-allocated ref
  amount_cents?: number;
  currency?: string;
  evidence?: GestaltRef[];    // must include evidence_bundle:invoice_payload
}

Response

Section titled “Response”
{
  "operation": "economy.invoice",
  "outcome": "admitted",
  "body": {
    "invoice": "invoice:fixture",
    "receivableObligation": "obligation:fixture",
    "closureSurface": "closure_surface:fixture",
    "rawConnectorPayloadExposed": false
  },
  "receipt": {...}
}

Refused with economic_invoice_evidence_missing if no evidence_bundle:invoice_payload is cited.

SDK example

Section titled “SDK example”
const invoice = await client.economicInvoice({
  tenant: "tenant_node:rheinwerk_calibration",
  amount_cents: 11900,
  currency: "EUR",
  evidence: ["evidence_bundle:invoice_payload"],
});

economy.paymentObservation

Section titled “economy.paymentObservation”

Observe matching payment evidence and settle the receivable obligation.

POST /v1/economy/payment-observation
state: staging-durable
sdk_role: observe matching payment evidence and settle the receivable obligation
request_record: CloudEconomicPaymentObservationRequest
responses: payment_observation | settlement | refusal | receipt

Request

Section titled “Request”
interface EconomicPaymentObservationRequest {
  tenant?: GestaltRef;
  invoice: GestaltRef;
  amount_cents?: number;
  currency?: string;
  evidence?: GestaltRef[];    // must include evidence_bundle:payment_observation
}

Response

Section titled “Response”
{
  "operation": "economy.paymentObservation",
  "outcome": "admitted",
  "body": {
    "paymentObservation": "payment_observation:fixture",
    "settlement": "settlement:fixture",
    "rawConnectorPayloadExposed": false
  },
  "receipt": {...}
}

Refused with economic_payment_evidence_missing if no evidence_bundle:payment_observation is cited.

The settlement closes the receivable closure surface that the invoice opened, if the amounts and currencies match.

economy.bookkeepingFact

Section titled “economy.bookkeepingFact”

Admit a bookkeeping fact only after invoice payment and advisor evidence.

POST /v1/economy/bookkeeping-fact
state: staging-durable
sdk_role: admit bookkeeping fact only after invoice payment and advisor evidence
request_record: CloudEconomicBookkeepingFactRequest
responses: bookkeeping_fact | refusal | receipt

Request

Section titled “Request”
interface EconomicBookkeepingFactRequest {
  tenant?: GestaltRef;
  invoice: GestaltRef;
  payment_observation: GestaltRef;
  advisor_evidence?: GestaltRef | null;
}

Refused with economic_bookkeeping_evidence_incomplete if advisor_evidence is not provided.

Response

Section titled “Response”
{
  "operation": "economy.bookkeepingFact",
  "outcome": "admitted",
  "body": {
    "bookkeepingFact": "bookkeeping_fact:fixture",
    "rawConnectorPayloadExposed": false
  },
  "receipt": {...}
}

economy.periodClose

Section titled “economy.periodClose”

Gate period close on resolved closure surfaces and explicit clearance evidence.

POST /v1/economy/period-close
state: fixture-rehearsed
sdk_role: gate period close on resolved closure surfaces and explicit clearance evidence
request_record: CloudEconomicPeriodCloseRequest
responses: period_close | refusal | receipt

Request

Section titled “Request”
interface EconomicPeriodCloseRequest {
  tenant?: GestaltRef;
  period?: string;            // e.g. "2026-04"
  evidence?: GestaltRef[];    // must include evidence_bundle:closure_clearance
}

Response

Section titled “Response”

Admitted:

{
  "operation": "economy.periodClose",
  "outcome": "admitted",
  "body": {
    "periodClose": "period_close:fixture",
    "productionAdmission": false
  },
  "receipt": {...}
}

Refused (open closure surface):

Refused with economic_closure_surface_open if any closure surface in the period is unresolved.

SDK example

Section titled “SDK example”
const close = await client.economicPeriodClose({
  tenant: "tenant_node:rheinwerk_calibration",
  period: "2026-04",
  evidence: ["evidence_bundle:closure_clearance"],
});

Combined flow

Section titled “Combined flow”
const invoice = await client.economicInvoice({
  tenant: "tenant_node:rheinwerk_calibration",
  amount_cents: 11900,
  currency: "EUR",
  evidence: ["evidence_bundle:invoice_payload"],
});


const payment = await client.economicPaymentObservation({
  tenant: "tenant_node:rheinwerk_calibration",
  invoice: invoice.body.invoice,
  amount_cents: 11900,
  currency: "EUR",
  evidence: ["evidence_bundle:payment_observation"],
});


const bookkeeping = await client.economicBookkeepingFact({
  tenant: "tenant_node:rheinwerk_calibration",
  invoice: invoice.body.invoice,
  payment_observation: payment.body.paymentObservation,
  advisor_evidence: "evidence_bundle:steuerberater_review",
});


const close = await client.economicPeriodClose({
  tenant: "tenant_node:rheinwerk_calibration",
  period: "2026-04",
  evidence: ["evidence_bundle:closure_clearance"],
});

For a single-call vertical that orchestrates all of this, see vertical-de-invoice-payment-advisor.md.

Refusal codes

Section titled “Refusal codes”
economic_invoice_evidence_missing
economic_payment_evidence_missing
economic_bookkeeping_evidence_incomplete
economic_closure_surface_open
required_evidence_missing
Section titled “Where to read next”