Heads up — PaymentNotice and PaymentReconciliation are on the roadmap. Until those resources ship, payments and reconciliations are tracked through Account (to aggregate charges) and Invoice (to itemize and settle). This page describes that pattern.

Account — Aggregating Charges

Account aggregates all billable activity for a patient over a period (an inpatient stay, a billing cycle, a single encounter).

curl -X POST https://api.esus.health/fhir/Account \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "active",
    "name": "Inpatient stay — April 2026",
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "servicePeriod": {
      "start": "2026-04-15",
      "end": "2026-04-21"
    },
    "coverage": [
      {
        "coverage": { "reference": "Coverage/c1a2e3d4-5b6f-7890-abcd-ef1234567890" },
        "priority": 1
      }
    ]
  }'

Invoice — Settling an Account

Invoice is the document you issue to a payer or patient. It itemizes the services and records the amount due or paid.

curl -X POST https://api.esus.health/fhir/Invoice \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "issued",
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "accountId": "aa11bb22-cc33-dd44-ee55-ff6677889900",
    "recipient": {
      "reference": "Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "date": "2026-04-22",
    "lineItem": [
      {
        "sequence": 1,
        "chargeItemCodeableConcept": {
          "coding": [{
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "99213",
            "display": "Office visit, established patient"
          }]
        },
        "priceComponent": [{
          "type": "base",
          "amount": { "value": 150.00, "currency": "USD" }
        }]
      }
    ],
    "totalNet":   { "value": 150.00, "currency": "USD" },
    "totalGross": { "value": 168.00, "currency": "USD" },
    "paymentTerms": "Payment due within 30 days."
  }'

Invoice Statuses

Account Statuses

Outstanding Balances

# All active accounts for a patient
curl "https://api.esus.health/fhir/Account?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

# All unpaid invoices for a patient
curl "https://api.esus.health/fhir/Invoice?subject=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=issued" \
  -H "Authorization: Bearer YOUR_TOKEN"

Recording a Payment

Until the dedicated PaymentNotice resource ships, the recommended pattern is:

1. Move the Invoice to balanced when the total is paid in full.
2. Record the payment metadata (amount, date, method, reference number) in Invoice.note[] or in your own ledger keyed by Invoice/<uuid>.
3. For partial payments, keep the Invoice in issued and track the remaining balance externally — the next release will replace this with structured PaymentNotice and PaymentReconciliation records.