Billing Periods

warning

Satxuma is still under active development. It is not yet HIPAA compliant and should only be used with dummy data.

A billing period determines, for a given admission:

• which services to bill for
• which payors should be billed for services
• the percentage order in which to bill each payor

This ensures that claims go to the correct payor(s) and that balances are distributed appropriately between insurance and the patient.

---

Data model

Satxuma stores billing periods under an admission:

A single billing period may reference one or more coverages.

Properties

A Billing Period has the following properties:

• disciplineIds (DisciplineId[])
  The list of therapy disciplines (e.g., PT, OT, SLP) that are active for this billing period.

• id (UUID)
  A unique identifier for the billing period.

• pdpmAssessment (PDPMAssessment, optional)
  Present only if the payor is Medicare Part A or Managed Care Part A. Contains assessment scores and related details:

  • isEstimate (boolean) – Whether the assessment is estimated.
  • notes (string) – Free-text notes for the assessment.
  • referenceDate (string) – The date the assessment references (ISO 8601 format).
  • scores (object) – Contains the following numeric scores (or null if not applicable):
    • PT – Physical Therapy
    • OT – Occupational Therapy
    • SLP – Speech-Language Pathology
    • N – Nursing
    • NTA – Non-Therapy Ancillary

• sequentialCoverages ({ splitCoverages: { id: string; payor: { id: string; name: string; type: PayorType }; percent: number }[] }[])
  A list of coverage segments for the billing period. Each sequential coverage contains:

  • splitCoverages (array) – One or more payor splits that cover the billing period. Each has:
    • id (string) – Unique identifier for the coverage split.
    • payor (object) – The associated payor:
      • id (string) – Unique identifier for the payor.
      • name (string) – Name of the payor.
      • type (PayorType) – Type of payor (e.g., Medicare Part A, Medicare Part B, Medicaid, etc.).
    • percent (number) – The percentage of the billing period covered by this payor split.

• startUTC (Timestamp | Date | 'parentStart')
  The UTC start date of the billing period, or the literal 'parentStart' if it inherits from a parent period.

Examples

Example 1: Simple billing period without PDPM assessment

{
  "disciplineIds": ["PT", "OT"],
  "id": "7f6a9a55-8e1b-4a3c-92c0-1fbb4f7bda1d",
  "sequentialCoverages": [
    {
      "splitCoverages": [
        {
          "id": "cov_001",
          "payor": {
            "id": "payor_123",
            "name": "Blue Cross Managed Care",
            "type": "Managed Care"
          },
          "percent": 100
        }
      ]
    }
  ],
  "startUTC": "2025-09-01T00:00:00Z"
}

Example 2: Medicare Part A billing period with PDPM assessment

{
  "disciplineIds": ["PT", "OT", "SLP", "N"],
  "id": "b82ef322-3fa4-4df7-9b20-482a8c3c482d",
  "pdpmAssessment": {
    "isEstimate": false,
    "notes": "Initial 5-day assessment",
    "referenceDate": "2025-09-01",
    "scores": {
      "PT": 16,
      "OT": 14,
      "SLP": 12,
      "N": 10,
      "NTA": 6
    }
  },
  "sequentialCoverages": [
    {
      "splitCoverages": [
        {
          "id": "cov_002",
          "payor": {
            "id": "payor_medA",
            "name": "Medicare Part A",
            "type": "Medicare Part A"
          },
          "percent": 100
        }
      ]
    }
  ],
  "startUTC": "2025-09-01T00:00:00Z"
}

Example 3: Split coverage between two payors

{
  "disciplineIds": ["PT"],
  "id": "33a5db63-1e27-4b4a-9d77-2e3f1e8c73aa",
  "sequentialCoverages": [
    {
      "splitCoverages": [
        {
          "id": "cov_003",
          "payor": {
            "id": "payor_medB",
            "name": "Medicare Part B",
            "type": "Medicare Part B"
          },
          "percent": 60
        },
        {
          "id": "cov_004",
          "payor": {
            "id": "payor_private",
            "name": "Private Pay",
            "type": "Private"
          },
          "percent": 40
        }
      ]
    }
  ],
  "startUTC": "2025-09-01T00:00:00Z"
}

Example 4: Sequential and split payors

{
  "disciplineIds": ["PT", "OT", "SLP"],
  "id": "f5c7a912-2d4b-4c3a-a6f7-9c8e7b1d2a34",
  "sequentialCoverages": [
    {
      "splitCoverages": [
        {
          "id": "cov_101",
          "payor": {
            "id": "payor_medA",
            "name": "Medicare Part A",
            "type": "Medicare Part A"
          },
          "percent": 100
        }
      ]
    },
    {
      "splitCoverages": [
        {
          "id": "cov_102",
          "payor": {
            "id": "payor_medB",
            "name": "Medicare Part B",
            "type": "Medicare Part B"
          },
          "percent": 70
        },
        {
          "id": "cov_103",
          "payor": {
            "id": "payor_private",
            "name": "Private Pay",
            "type": "Private"
          },
          "percent": 30
        }
      ]
    }
  ],
  "startUTC": "2025-09-01T00:00:00Z"
}

Explanation:

• The first sequential coverage is fully covered by Medicare Part A.
• The second sequential coverage has a split: 70% Medicare Part B and 30% Private Pay.
• This structure allows the billing period to represent changes in coverage over time.