Scheduled Payments

The Scheduled Payment Calendar (SPC) is the structured payment plan agreed to in the surrogacy contract. It defines what the surrogate will be paid, how much, and when. Managing this correctly is critical — errors here affect real payments to real people.

What Is the SPC?

The SPC is a set of Compensation records on a case where calendar_date IS NOT NULL. Each record represents one scheduled payment — an amount due on a specific date.

Important: The Compensation model is overloaded. Records with calendar_date IS NOT NULL are SPC entries. Records with calendar_date IS NULL are DR types (categories of one-time disbursements). See Disbursement Requests for the DR type side.

Compensation Categories

SPC items are grouped into categories based on their code field. The FastAPI layer returns them grouped for display:

Category	What It Covers
`funding`	Initial escrow deposit milestones
`base`	Monthly base compensation
`bonus`	One-time bonuses (delivery, heartbeat, etc.)
`embryo_transfer`	Embryo transfer procedure payments
`allowance`	Monthly allowances
`maternity_clothing`	Maternity clothing allowance
`organic_food`	Organic food allowance
`multi_fetal`	Multiple fetus compensation
`travel`	Travel reimbursements
`insurance`	Insurance-related payments
`living`	Living expense payments
`personal`	Personal expense payments
`tech`	Technology allowance
`other`	Uncategorized items

Each category in the API response includes total (total amount) and remaining (unpaid amount).

SPC Item Fields

Field	Purpose
`calendar_date`	The date this payment is due. `NOT NULL` = SPC entry.
`amount`	Dollar amount of this payment
`title`	Display name
`code`	Internal code used for categorization
`paid`	`True` once the payment has been fully processed
`applicable`	Whether this item applies to this case
`active`	Whether this item is enabled
`journey_limit`	Maximum total that can be paid from this compensation type
`ordering`	Display order within category
`note`	Optional note shown to parties if `display_note = True`
`verification_required`	Whether documentation must be uploaded before payment
`payee_is_surrogate`	Whether the payment goes to the surrogate
`payee`	Override payee name if not the surrogate

Recurring SPC Items

Some payments recur on a schedule (e.g., monthly base compensation). These are configured with:

payment_start — first payment date
payment_end — last payment date
days_between — interval between payments

When an Admin creates a recurring SPC, the system generates individual Compensation records — one per payment — each with its own calendar_date. They are not dynamically generated; they all exist as rows in the database.

Interval logic:

days_between = 30 (or NULL) → adds exactly one calendar month, handling month-end edge cases (e.g., Jan 31 → Feb 28)
Any other value → adds exactly that many days

Example: A monthly base compensation from Jan 1 to Dec 31 creates 12 separate Compensation records: Jan 1, Feb 1, Mar 1… Dec 1.

How an SPC Item Becomes a Payment

Compensation record (calendar_date set, paid = False)
    ↓
First SPC: A legal admin manually approves the first DR in the payments dashboard.
  The payments dashboard shows different controls depending on the admin's permission set —
  a legal admin sees the approval action for the first scheduled payment.
Subsequent SPCs: processed automatically through the normal payment batch flow.
    ↓
LedgerTransaction created:
  - type = "SCHEDULED PAYMENT"
  - status = "PENDING"
  - compensation_id → links back to the Compensation record
    ↓
Included in disbursement batch (dr_batch_id assigned)
    ↓
Batch approved → LedgerTransaction status → PAID
    ↓
compensation.paid = True
    ↓
Notification emails sent (IP, Surrogate, Case Managers)

If this was the last SPC item in its category (base compensation, multi-fetal, or funding), an additional email is sent to the Admin notifying them the category is complete.

SPC Approval

SPC items do not have their own approval flow — they are approved as part of the disbursement batch process, the same way regular DRs are approved. The SPC item’s compensation_id is referenced on the resulting LedgerTransaction.

Compensation Templates

When a new case is created, the SPC can be pre-populated from a template. AgencyCompTemplate defines standard compensation types for an agency. When a template is applied to a case, it creates Compensation records using the template’s default amounts, which can then be adjusted per-case.

Journey Limit

Compensation.journey_limit sets a cap on the total amount that can be paid out from a given compensation category over the life of the case. This enforces contract limits without manual oversight.

SPC Change Tracking

When the Admin responsible for the SPC changes (spc_admin_id on the Case), an SPCChange record is created. This maintains a history of who was responsible for the payment schedule at any point in time — relevant for accountability and audit purposes.

API Reference

GET /api/cases/{case_id}/compensations/calendar — Returns all compensation items grouped by category with totals and remaining balances
POST /api/cases/{case_id}/transactions/deposit — Creates a deposit notification
SPC creation and editing is currently Flask-only (desktop admin UI)

Gotchas for Developers

Each recurring SPC payment is a separate database row. There is no “parent” recurring record with children. If you need to update all payments in a series, you must update each Compensation record individually.

paid = True is set by the transaction processing, not by the Admin. Do not manually set paid = True on a Compensation record — it is set automatically when the linked LedgerTransaction reaches PAID status.

journey_limit is a soft cap enforced in business logic, not a database constraint. If it is not correctly validated in the payment flow, overpayment is possible.