@rinse-dental/open-dental 3.4.2 → 4.0.2

package/docs/Open Dental 2026-04-22/apipatplans.md

@@ -0,0 +1,147 @@
+# API: PatPlans
+
+**Source:** https://www.opendental.com/site/apipatplans.html
+**Extracted:** 2026-04-22
+**Base Path:** `/patplans`
+
+---
+
+## Overview
+
+PatPlan rows represent a patient's insurance coverage assignments. The absence of a PatPlan row indicates no coverage. Coverage is managed by adding or removing PatPlan rows, not by modifying the underlying InsPlan directly.
+
+---
+
+## Endpoints
+
+### GET /patplans
+
+**Version:** 22.4.27
+**Description:** Retrieves PatPlan records matching specified criteria.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | No | — | FK to patient.PatNum |
+| InsSubNum | integer | No | — | FK to inssub.InsSubNum |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| PatPlanNum | integer | Primary key |
+| PatNum | integer | FK to patient.PatNum |
+| Ordinal | integer | Insurance priority (1=primary, 2=secondary, etc.) |
+| IsPending | boolean | Whether coverage is pending |
+| Relationship | string | Patient's relationship to subscriber (enum) |
+| PatID | string | Overrides subscriber ID on eClaims; used for Canada |
+| InsSubNum | integer | FK to inssub.InsSubNum |
+| OrthoAutoFeeBilledOverride | decimal | Override for ortho auto-billed fee |
+| OrthoAutoNextClaimDate | date | Next ortho auto-claim date |
+| SecDateTEntry | datetime | Entry timestamp |
+| SecDateTEdit | datetime | Last edit timestamp |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /patplans
+
+**Version:** 21.1
+**Description:** Creates a new PatPlan, assigning insurance coverage to a patient.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| InsSubNum | integer | Yes | FK to inssub.InsSubNum; must reference an existing InsSub; returns BadRequest if already linked |
+| Ordinal | integer | No | Priority digit 1–9; default: 1; setting to 1 bumps existing primary to Ordinal 2 |
+| Relationship | string | No | Default: "Self" |
+| PatID | string | No | Overrides subscriber ID on eClaims; used for Canada (v21.4+) |
+
+**Response:** object — created PatPlan record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest (missing/invalid fields or InsSub already linked) |
+| 404 | NotFound (patient does not exist) |
+
+---
+
+### PUT /patplans/{PatPlanNum}
+
+**Version:** 21.4
+**Description:** Updates an existing PatPlan. PatNum cannot be modified.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatPlanNum | integer | Yes | Primary key of the PatPlan |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| InsSubNum | integer | No | Change subscriber (corresponds to Change button in Subscriber Information UI) |
+| Ordinal | integer | No | Priority digit 1–9; setting to 1 bumps existing primary to Ordinal 2 |
+| Relationship | string | No | Relationship enum value |
+| PatID | string | No | Overrides subscriber ID on eClaims; used for Canada |
+
+**Response:** object — updated PatPlan record
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound (InsSub does not exist) |
+
+---
+
+### DELETE /patplans/{PatPlanNum}
+
+**Version:** 21.1
+**Description:** Removes a PatPlan record (called "Drop" in the UI). Does not affect the underlying InsPlan.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatPlanNum | integer | Yes | Primary key of the PatPlan |
+
+**Response:** 200 OK
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+
+---
+
+## Field Reference
+
+### Relationship (enum)
+| Value | Description |
+|-------|-------------|
+| Self | Patient is the subscriber |
+| Spouse | Spouse of subscriber |
+| Child | Child of subscriber |
+| Employee | Employee of subscriber |
+| HandicapDep | Handicapped dependent |
+| SignifOther | Significant other |
+| InjuredPlantiff | Injured plaintiff |
+| LifePartner | Life partner |
+| Dependent | Dependent |
+
+---
+
+## Implementation Notes
+
+- Ordinal 1 = primary insurance; ordinal 2 = secondary; etc.; valid values are single digits 1–9
+- Setting Ordinal to 1 automatically bumps the existing primary plan to Ordinal 2
+- DELETE removes coverage assignment only; InsPlan and InsSub records are unaffected
+- PatNum cannot be changed via PUT

package/docs/Open Dental 2026-04-22/apipayments.md

@@ -0,0 +1,236 @@
+# API: Payments
+
+**Source:** https://www.opendental.com/site/apipayments.html
+**DB Schema Ref:** payment
+**Extracted:** 2026-04-22
+**Base Path:** `/payments`
+
+---
+
+## Overview
+
+The Payments API manages patient payment records. Payments always have at least one associated paysplit. On creation, payments are automatically applied to outstanding charges in FIFO order; overpayments become unearned income. The API supports retrieval, standard creation, refund creation, updating payment metadata, and partial re-splitting.
+
+---
+
+## Endpoints
+
+### GET /payments
+
+**Version:** 22.2.32
+**Description:** Retrieves a list of payments with optional filtering.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | Conditionally required | — | FK to patient.PatNum; required prior to v23.3.11 |
+| PayType | integer | No | — | FK to definition.DefNum where definition.Category=10 (v23.3.11+) |
+| DateEntry | string | No | — | Format: yyyy-MM-dd; retrieves payments on or after this date |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| PayNum | integer | Primary key |
+| PayType | integer | FK to definition.DefNum (Category=10); 0 if income transfer |
+| payType | string | Human-readable payment type (e.g., "Check") |
+| PayDate | string | Payment display date, format: yyyy-MM-dd |
+| PayAmt | string | Payment amount (currency) |
+| CheckNum | string | Check number |
+| BankBranch | string | Bank-branch code (e.g., 19-7076) |
+| PayNote | string | Administrative note (not visible to patient; UI limit: 4000 chars) |
+| PatNum | integer | FK to patient.PatNum |
+| ClinicNum | string | FK to clinic.ClinicNum; 0 if unassigned |
+| DateEntry | string | Entry date (not user-editable), format: yyyy-MM-dd |
+| DepositNum | integer | FK to deposit.DepositNum; 0 if not attached to deposit |
+| Receipt | string | Text of electronic payment receipt for reprinting |
+| IsRecurringCC | boolean | True if automatically added recurring CC charge |
+| SecUserNumEntry | integer | FK to userod.UserNum |
+| SecDateTEdit | string | Last edit timestamp (yyyy-MM-dd HH:mm:ss) |
+| PaymentSource | string | Origin of payment (enum: CreditCardSource) |
+| ProcessStatus | string | Processing status (enum: ProcessStat) |
+| RecurringChargeDate | string | Date of recurring charge this payment applies to, format: yyyy-MM-dd |
+| IsCcCompleted | boolean | True if CC transaction is completed (disables CC buttons to prevent duplicates) |
+| MerchantFee | decimal | Additional transaction fee for display/reporting |
+| serverDateTime | string | Server datetime (yyyy-MM-dd HH:mm:ss) |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /payments
+
+**Version:** 21.2
+**Description:** Creates a payment for a patient. Applies to outstanding charges in FIFO order; overpayments become unearned income.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayAmt | string | Yes | Currency amount |
+| PatNum | integer | Yes | FK to patient.PatNum |
+| PayType | integer | No | FK to definition.DefNum (Category=10); defaults to ApiPaymentType preference (v23.1.27+) |
+| PayDate | string | No | Format: yyyy-MM-dd; defaults to today; respects office future-dated payment preference |
+| CheckNum | string | No | Check number |
+| PayNote | string | No | Administrative note |
+| BankBranch | string | No | Bank-branch code |
+| ClinicNum | integer | No | FK to clinic; defaults to patient.ClinicNum |
+| isPatientPreferred | boolean | No | If true, directs splits to patient instead of family FIFO; default: false |
+| isPrepayment | boolean | No | Creates single unearned paysplit using PrepaymentUnearnedType preference; default: false (v22.4.8+) |
+| isUnallocatedPrepayment | boolean | No | Creates unallocated paysplit with no unearned type; overrides RigorousAccounting pref (only for pref=1 "Auto-Split"); ignored if pref=0 "Rigorous"; default: false (v25.4.42+) |
+| procNums | array of integers | No | Apply payment to specific procedures by ProcDate FIFO; silently ignores procs outside patient's family; ignored if isPrepayment=true; default: empty (v22.4.16+) |
+| payPlanNum | integer | No | FK to payplan.PayPlanNum for Dynamic Payment Plan; only allowed with isPrepayment=true (pre-v23.3.4); default: 0 (v23.1.31+) |
+| MerchantFee | decimal | No | Additional transaction fee for display; default: 0.0 (v25.4.15+) |
+
+**Response:** object (same fields as GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /payments/Refund
+
+**Version:** 24.4.28
+**Description:** Creates a refund payment. PayAmt in the response will be negative.
+
+**Restrictions:** Cannot refund payments attached to payment plans or containing negative paysplits.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayNum | integer | Yes | FK to the payment to refund |
+
+**Response:** object (same fields as GET; PayAmt will be negative)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /payments/{PayNum}
+
+**Version:** 23.3.11
+**Description:** Updates payment metadata fields.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayNum | integer | Yes | Primary key of the payment |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayType | integer | No | FK to definition.DefNum (Category=10) |
+| CheckNum | string | No | Overwrites existing value |
+| BankBranch | string | No | Overwrites existing value |
+| PayNote | string | No | Overwrites existing value |
+| ProcessStatus | string | No | Enum: "OnlineProcessed" or "OnlinePending" (v24.3.26+) |
+
+**Response:** object (same fields as GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /payments/{PayNum}/Partial
+
+**Version:** 25.1.11
+**Description:** Deletes existing paysplits and creates new ones for specified procedures and/or payment plan charges. The sum of all allocated amounts must equal the payment's PayAmt.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayNum | integer | Yes | Primary key of an existing payment |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| procNumsAndAmounts | array of objects | Conditionally required | Required unless payPlanChargeNumsAndAmounts is provided |
+| procNumsAndAmounts[].ProcNum | integer | Yes (within array) | FK to procedurelog.ProcNum; must have outstanding charge; can be family member's; TP procedures allowed if PrePayAllowedForTpProcs preference enabled |
+| procNumsAndAmounts[].Amount | decimal | Yes (within array) | Amount to allocate to this procedure |
+| payPlanChargeNumsAndAmounts | array of objects | Conditionally required | Required unless procNumsAndAmounts is provided (v25.2.45+) |
+| payPlanChargeNumsAndAmounts[].PayPlanChargeNum | integer | Yes (within array) | FK to payplancharge.PayPlanChargeNum; must belong to Dynamic Payment Plan for patient or family member |
+| payPlanChargeNumsAndAmounts[].Amount | decimal | Yes (within array) | Amount to allocate to this charge |
+
+**Response:** object (same fields as GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### PaymentSource (enum: CreditCardSource)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | Not a credit card payment (or CC number stored directly — not recommended) |
+| XServer | 1 | Local installation of X-Charge |
+| XWeb | 2 | X-Web eService |
+| PayConnect | 3 | PayConnect web service (from within OD) |
+| XServerPayConnect | 4 | X-Charge local + PayConnect web service |
+| XWebPortalLogin | 5 | Patient Portal login screen |
+| PaySimple | 6 | PaySimple web service |
+| PaySimpleACH | 7 | PaySimple ACH web service |
+| PayConnectPortal | 8 | PayConnect from Patient Portal |
+| PayConnectPortalLogin | 9 | PayConnect from Patient Portal login screen |
+| CareCredit | 10 | CareCredit |
+| EdgeExpressRCM | 11 | Global Payments V1 Cloud via RCM program |
+| EdgeExpressCNP | 12 | Global Payments V1 Card Not Present API |
+| API | 13 | Payment taken through Open Dental API |
+| EdgeExpressPaymentPortal | 14 | Global Payments V1 via Payment Portal |
+| EdgeExpressPaymentPortalGuest | 15 | Global Payments V1 via Payment Portal (guest) |
+| PayConnectPaymentPortal | 16 | PayConnect via Payment Portal |
+| PayConnectPaymentPortalGuest | 17 | PayConnect via Payment Portal (guest) |
+| PaySimplePaymentPortal | 18 | PaySimple via Payment Portal |
+| PaySimplePaymentPortalGuest | 19 | PaySimple via Payment Portal (guest) |
+| PaySimplePaymentPortalACH | 20 | PaySimple ACH via Payment Portal |
+| XWebPaymentPortal | 21 | XWeb via Payment Portal |
+| XWebPaymentPortalGuest | 22 | XWeb via Payment Portal (guest) |
+| MeetInTheCloudTerminal | 23 | Global Payments V2 via terminal |
+
+### ProcessStatus (enum: ProcessStat)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| OfficeProcessed | 0 | Payment made within OD program |
+| OnlineProcessed | 1 | Payment made from Patient Portal; processed within OD |
+| OnlinePending | 2 | Payment made from Patient Portal; needs processing within OD |
+
+---
+
+## Implementation Notes
+
+- Payments always require at least one paysplit; PayAmt must equal the sum of all paysplits
+- FIFO allocation applies to the oldest eligible payment plan if the patient has multiple
+- `isPrepayment=true` creates a single unearned paysplit using the PrepaymentUnearnedType preference
+- `isUnallocatedPrepayment=true` only valid when RigorousAccounting preference is "Auto-Split" (1); ignored when pref is "Rigorous" (0)
+- Cannot refund payments attached to payment plans or containing negative paysplits
+- PUT /Partial replaces all existing paysplits; sum of all Amount values must exactly equal PayAmt
+- ClinicNum on payment need not match ClinicNum on paysplits; payments can be split across clinics
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /paysplits | Individual allocation records for each payment |
+| /payplans | Payment plan that may receive prepayments |

package/docs/Open Dental 2026-04-22/apipayplancharges.md

@@ -0,0 +1,59 @@
+# API: PayPlanCharges
+
+**Source:** https://www.opendental.com/site/apipayplancharges.html
+**Extracted:** 2026-04-22
+**Base Path:** `/payplancharges`
+
+---
+
+## Overview
+The PayPlanCharges API retrieves charge records associated with a payment plan. Each charge record represents a scheduled principal or interest debit within the payment plan structure.
+
+---
+
+## Endpoints
+
+### GET /payplancharges
+
+**Version:** 23.2.28
+**Description:** Retrieves all pay plan charges for a specified payment plan.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PayPlanNum | integer | Yes | — | FK to payment plan; identifies the payment plan for which charges are retrieved |
+
+**Response:** array of objects
+| Field | Type | Description |
+|-------|------|-------------|
+| PayPlanChargeNum | integer | Unique identifier for the charge record |
+| PayPlanNum | integer | FK to associated payment plan |
+| Guarantor | integer | Guarantor patient number |
+| PatNum | integer | Patient number |
+| ChargeDate | date | Date of the charge (YYYY-MM-DD) |
+| Principal | decimal | Principal amount charged |
+| Interest | decimal | Interest amount charged |
+| Note | string | Optional note or description |
+| ProvNum | integer | FK to provider |
+| ClinicNum | integer | FK to clinic |
+| ChargeType | string | Type of charge (e.g., "Debit") |
+| ProcNum | integer | FK to procedure |
+| SecDateTEntry | datetime | Timestamp of record creation |
+| SecDateTEdit | datetime | Timestamp of last modification |
+| StatementNum | integer | FK to statement |
+| FKey | integer | Foreign key reference |
+| LinkType | string | Link type (e.g., "Procedure") |
+| IsOffset | boolean | Indicates offset status |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Implementation Notes
+- `PayPlanNum` query parameter is required; requests without it will return 400 BadRequest.
+- This endpoint is read-only; no POST, PUT, or DELETE operations are available.

package/docs/Open Dental 2026-04-22/apipayplans.md

@@ -0,0 +1,256 @@
+# API: PayPlans
+
+**Source:** https://www.opendental.com/site/apipayplans.html
+**DB Schema Ref:** payplan
+**Extracted:** 2026-04-22
+**Base Path:** `/payplans`
+
+---
+
+## Overview
+
+The PayPlans API manages payment plans in Open Dental. Three plan types exist: Dynamic (current standard), Insurance, and Patient (deprecated in v23.3.1). Dynamic Payment Plans are now simply called "Payment Plans" in the UI. Insurance plans have PlanNum > 0 AND InsSubNum > 0; Dynamic plans have IsDynamic=true; Patient plans are neither.
+
+---
+
+## Endpoints
+
+### GET /payplans/{PayPlanNum}
+
+**Version:** 24.4.30
+**Description:** Retrieves a single payment plan by primary key.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayPlanNum | integer | Yes | Primary key of the payment plan |
+
+**Response:** object
+| Field | Type | Description |
+|-------|------|-------------|
+| PayPlanNum | integer | Primary key |
+| PatNum | integer | FK to patient.PatNum (patient who had treatment done) |
+| Guarantor | integer | FK to patient.PatNum (person responsible for payments; need not be same family) |
+| PayPlanDate | date | Date the plan displays in the account |
+| APR | decimal | Annual percentage rate (e.g., 18.0); used for amortization only |
+| Note | string | Plan terms; auto-generated when amortization schedule created |
+| PlanNum | integer | FK to insplan.PlanNum; 0 for patient/dynamic plans; set for insurance plans |
+| CompletedAmt | decimal | Amount of treatment already completed (Dynamic plans only) |
+| InsSubNum | integer | FK to inssub.InsSubNum; 0 for patient/dynamic plans; set for insurance plans |
+| PaySchedule | string | Payment frequency (legacy; enum: PaymentSchedule) |
+| NumberOfPayments | integer | Total number of payments in plan |
+| PayAmt | decimal | Amount per payment plan charge |
+| DownPayment | decimal | Initial payment when plan was opened |
+| IsClosed | boolean | True if plan is closed |
+| PlanCategory | integer | FK to definition.DefNum |
+| planCategory | string | Category name |
+| IsDynamic | boolean | True if Dynamic payment plan |
+| ChargeFrequency | string | Charge creation frequency (enum: PayPlanFrequency); Dynamic plans only |
+| DatePayPlanStart | date | Date of first payment plan charge (excludes down payment); Dynamic plans only |
+| IsLocked | boolean | True if plan is locked; locked plans cannot add production or modify terms |
+| DateInterestStart | date | Date interest begins accruing |
+| DynamicPayPlanTPOption | string | How TP procedures are handled (enum: DynamicPayPlanTPOptions) |
+| principalAmount | decimal | Principal amount of the plan |
+| SheetDefNum | integer | FK to sheetdef.SheetDefNum; 0 uses hard-coded logic |
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### GET /payplans
+
+**Version:** 22.2.16
+**Description:** Retrieves payment plans for a patient or guarantor.
+
+**Query Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| PatNum | integer | Conditionally required | — | FK to patient.PatNum; required if Guarantor not provided |
+| Guarantor | integer | Conditionally required | — | FK to patient.PatNum; required if PatNum not provided |
+
+**Response:** array of objects (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 404 | NotFound |
+
+---
+
+### POST /payplans/Dynamic
+
+**Version:** 22.2.22
+**Description:** Creates a new Dynamic Payment Plan.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| PayAmt | decimal | Conditionally required | Amount per payment; required if NumberOfPayments not provided |
+| NumberOfPayments | integer | Conditionally required | Total payments (calculates PayAmt); required if PayAmt not provided |
+| procNums | array of integers | Conditionally required | Procedure identifiers; required if adjNums not provided |
+| adjNums | array of integers | Conditionally required | Adjustment identifiers; required if procNums not provided |
+| Guarantor | integer | No | Defaults to patient |
+| PayPlanDate | date | No | Defaults to today |
+| APR | decimal | No | Defaults to 0 |
+| DownPayment | decimal | No | Defaults to 0.00 |
+| Note | string | No | Appended to system-generated terms |
+| PlanCategory | integer | No | FK to definition.DefNum; default: 0 ("None") (v25.3.31+) |
+| ChargeFrequency | string | No | Enum value; defaults to "Monthly" |
+| DatePayPlanStart | date | No | Defaults to one month after PayPlanDate |
+| DateInterestStart | date | No | Defaults to minimum value |
+| IsLocked | boolean | No | Defaults to true; must be true if APR > 0 |
+| DynamicPayPlanTPOption | string | No | Defaults to "AwaitComplete" |
+
+**Response:** object (same fields as single GET; PayPlanNum auto-generated)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### POST /payplans
+
+**Version:** 22.4.39 (Deprecated in 23.3.1)
+**Description:** Creates a Patient Payment Plan. **Deprecated** — use POST /payplans/Dynamic instead.
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PatNum | integer | Yes | FK to patient.PatNum |
+| useEstBalance | boolean | Conditionally required | Use patient's estimated balance; required if principalAmount not provided |
+| principalAmount | decimal | Conditionally required | Plan amount; required if useEstBalance not provided |
+| PayAmt | decimal | Conditionally required | Amount per payment; required if NumberOfPayments not provided |
+| NumberOfPayments | integer | Conditionally required | Total payments; required if PayAmt not provided |
+| Guarantor | integer | No | Defaults to patient |
+| PayPlanDate | date | No | Defaults to today |
+| APR | decimal | No | Defaults to 0 |
+| DownPayment | decimal | No | Defaults to 0.00 |
+| Note | string | No | Appended to system-generated terms |
+| ChargeFrequency | string | No | Defaults to "Monthly" |
+| DatePayPlanStart | date | No | Defaults to one month after PayPlanDate |
+| DateInterestStart | date | No | Defaults to minimum value |
+
+**Response:** text string describing plan terms and costs
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 201 | Created |
+| 400 | BadRequest |
+| 404 | NotFound |
+| 410 | Gone (Deprecated) |
+
+---
+
+### PUT /payplans/{PayPlanNum}/Close
+
+**Version:** 22.4.39
+**Description:** Closes a single patient or Dynamic payment plan. Cannot close insurance plans.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayPlanNum | integer | Yes | Primary key of the payment plan |
+
+**Response:** object (same fields as single GET; IsClosed=true)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+### PUT /payplans/{PayPlanNum}/Dynamic
+
+**Version:** 25.3.31
+**Description:** Updates an existing Dynamic Payment Plan.
+
+**Path Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayPlanNum | integer | Yes | Primary key of the payment plan |
+
+**Body Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| PayAmt | decimal | No | Amount per payment; cannot be used with NumberOfPayments |
+| NumberOfPayments | integer | No | Total payments (calculates PayAmt); cannot be used with PayAmt |
+| Guarantor | integer | No | Cannot change if plan has existing charges/payments |
+| PayPlanDate | date | No | Cannot be future date if FutureTransDatesAllowed is disabled |
+| APR | decimal | No | Requires IsLocked=true if PayPlanRequireLockForAPR preference enabled |
+| Note | string | No | Overwrites existing note |
+| PlanCategory | integer | No | FK to definition.DefNum; 0 = "None" |
+| ChargeFrequency | string | No | Enum: ChargeFrequency values |
+| DatePayPlanStart | date | No | Cannot change if plan has existing charges |
+| DateInterestStart | date | No | Only allowed if APR > 0 |
+| IsLocked | boolean | No | Required true if APR > 0 and PayPlanRequireLockForAPR enabled |
+| SheetDefNum | integer | No | Only allowed if PayPlansUseSheets preference enabled |
+
+**Response:** object (same fields as single GET)
+
+**Status Codes:**
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 400 | BadRequest |
+| 404 | NotFound |
+
+---
+
+## Field Reference
+
+### ChargeFrequency (enum: PayPlanFrequency) — Dynamic plans only
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| Weekly | 0 | Every week |
+| EveryOtherWeek | 1 | Every other week |
+| OrdinalWeekday | 2 | Monthly, same week and day (e.g., 3rd Friday) |
+| Monthly | 3 | Once per month |
+| Quarterly | 4 | Four times per year |
+
+### DynamicPayPlanTPOption (enum: DynamicPayPlanTPOptions)
+| Value | DB Int | Description |
+|-------|--------|-------------|
+| None | 0 | No TP option set |
+| AwaitComplete | 1 | Wait for TP procedures to be completed before charging |
+| TreatAsComplete | 2 | Treat TP procedures as already complete for charging purposes |
+
+### Plan Type Identification
+| Plan Type | Condition |
+|-----------|-----------|
+| Insurance | PlanNum > 0 AND InsSubNum > 0 |
+| Dynamic | IsDynamic = true |
+| Patient (deprecated) | Neither of the above |
+
+---
+
+## Implementation Notes
+
+- Patient Payment Plans were deprecated in v23.3.1; use Dynamic Payment Plans instead
+- POST /payplans returns 410 Gone in versions that have fully deprecated patient plans
+- IsLocked=true is required when APR > 0 (if PayPlanRequireLockForAPR preference is enabled)
+- Locked plans cannot add production or modify terms; unlocking requires PayPlanUnlock permission
+- DatePayPlanStart and CompletedAmt are only meaningful for Dynamic payment plans
+- Guarantor on a plan does not need to be in the same family as the patient
+- PUT /Dynamic: Guarantor cannot change if plan has existing charges or payments
+- PUT /Dynamic: DatePayPlanStart cannot change if plan has existing charges
+
+## Related Resources
+| Resource | Purpose |
+|----------|---------|
+| /payments | Payments that can be applied to payment plans |
+| /paysplits | Individual split records for payment plan payments |