Billing API

Base URL: /api/v1/billing/

Manage tuition billing, fee configuration, payment plans, transactions, refund schedules, and student billing calculations.

Endpoints Overview

Settings

Method	Endpoint	Description
GET	/settings	List billing settings
POST	/settings	Create billing setting
GET	/settings/{settingID}	Get setting details
PATCH	/settings/{settingID}	Update setting
DELETE	/settings/{settingID}	Delete setting

Billing Methods

Method	Endpoint	Description
GET	/methods	List billing methods
POST	/methods	Create billing method
GET	/methods/{methodID}	Get method details
PATCH	/methods/{methodID}	Update method
DELETE	/methods/{methodID}	Delete method
GET	/methods/{methodID}/configs	List method configs
POST	/methods/{methodID}/configs	Create method config
GET	/methods/{methodID}/bands	List method bands
POST	/methods/{methodID}/bands	Create method band
GET	/methods/{methodID}/credit_rates	List method credit rates
POST	/methods/{methodID}/credit_rates	Create method credit rate

Method Configs (standalone)

Method	Endpoint	Description
GET	/method-configs	List all method configs
PATCH	/method-configs/{configID}	Update method config
DELETE	/method-configs/{configID}	Delete method config

Billing Bands (standalone)

Method	Endpoint	Description
GET	/bands	List all billing bands
PATCH	/bands/{bandID}	Update billing band
DELETE	/bands/{bandID}	Delete billing band

Credit Rates (standalone)

Method	Endpoint	Description
GET	/credit-rates	List all credit rates
PATCH	/credit-rates/{rateID}	Update credit rate
DELETE	/credit-rates/{rateID}	Delete credit rate

Fee Types

Method	Endpoint	Description
GET	/fee-types	List fee types
POST	/fee-types	Create fee type
GET	/fee-types/{feeTypeID}	Get fee type details
PATCH	/fee-types/{feeTypeID}	Update fee type
DELETE	/fee-types/{feeTypeID}	Delete fee type

Term Fees

Method	Endpoint	Description
GET	/term-fees	List term fees
POST	/term-fees	Create term fee
GET	/term-fees/{termFeeID}	Get term fee details
PATCH	/term-fees/{termFeeID}	Update term fee
DELETE	/term-fees/{termFeeID}	Delete term fee
GET	/term-fees/{termFeeID}/bands	List term fee bands
POST	/term-fees/{termFeeID}/bands	Create term fee band
GET	/term-fees/{termFeeID}/categories	List term fee categories
POST	/term-fees/{termFeeID}/categories	Create term fee category

Term Fee Bands (standalone)

Method	Endpoint	Description
GET	/term-fee-bands	List all term fee bands
PATCH	/term-fee-bands/{bandID}	Update term fee band
DELETE	/term-fee-bands/{bandID}	Delete term fee band

Term Fee Categories (standalone)

Method	Endpoint	Description
GET	/term-fee-categories	List all term fee categories
PATCH	/term-fee-categories/{categoryID}	Update term fee category
DELETE	/term-fee-categories/{categoryID}	Delete term fee category
GET	/term-fee-categories/{categoryID}/bands	List category bands
POST	/term-fee-categories/{categoryID}/bands	Create category band

Term Fee Category Bands (standalone)

Method	Endpoint	Description
GET	/term-fee-category-bands	List all category bands
PATCH	/term-fee-category-bands/{bandID}	Update category band
DELETE	/term-fee-category-bands/{bandID}	Delete category band

Payment Plans

Method	Endpoint	Description
GET	/payment-plans	List payment plans
POST	/payment-plans	Create payment plan
GET	/payment-plans/{planID}	Get payment plan details
PATCH	/payment-plans/{planID}	Update payment plan
DELETE	/payment-plans/{planID}	Delete payment plan
GET	/payment-plans/{planID}/terms	List plan terms
POST	/payment-plans/{planID}/terms	Create plan term
GET	/payment-plans/{planID}/eligibility	List plan eligibility rules
POST	/payment-plans/{planID}/eligibility	Create plan eligibility rule
GET	/payment-plans/{planID}/fees	List plan fees
POST	/payment-plans/{planID}/fees	Create plan fee

Payment Plan Terms (standalone)

Method	Endpoint	Description
GET	/payment-plan-terms	List all plan terms
PATCH	/payment-plan-terms/{termID}	Update plan term
DELETE	/payment-plan-terms/{termID}	Delete plan term

Payment Plan Eligibility (standalone)

Method	Endpoint	Description
GET	/payment-plan-eligibility	List all eligibility rules
PATCH	/payment-plan-eligibility/{eligibilityID}	Update eligibility rule
DELETE	/payment-plan-eligibility/{eligibilityID}	Delete eligibility rule

Payment Plan Fees (standalone)

Method	Endpoint	Description
GET	/payment-plan-fees	List all plan fees
PATCH	/payment-plan-fees/{feeID}	Update plan fee
DELETE	/payment-plan-fees/{feeID}	Delete plan fee

Upfront Discounts

Method	Endpoint	Description
GET	/upfront-discounts	List upfront discounts
POST	/upfront-discounts	Create upfront discount
GET	/upfront-discounts/{discountID}	Get discount details
PATCH	/upfront-discounts/{discountID}	Update discount
DELETE	/upfront-discounts/{discountID}	Delete discount

Transactions

Method	Endpoint	Description
GET	/transactions	List transactions
POST	/transactions	Create transaction
GET	/transactions/{transactionID}	Get transaction details

Refund Schedules

Method	Endpoint	Description
GET	/refund-schedules	List refund schedules
POST	/refund-schedules	Create refund schedule
GET	/refund-schedules/{scheduleID}	Get schedule details
PATCH	/refund-schedules/{scheduleID}	Update schedule
DELETE	/refund-schedules/{scheduleID}	Delete schedule
GET	/refund-schedules/{scheduleID}/entries	List schedule entries
POST	/refund-schedules/{scheduleID}/entries	Create schedule entry

Refund Schedule Entries (standalone)

Method	Endpoint	Description
GET	/refund-schedule-entries	List all schedule entries
PATCH	/refund-schedule-entries/{entryID}	Update schedule entry
DELETE	/refund-schedule-entries/{entryID}	Delete schedule entry

Student Billing

Method	Endpoint	Description
GET	/students/{studentID}/balance/{termID}	Get student balance for term
GET	/students/{studentID}/payment-plans/{termID}	Get student payment plans for term
GET	/students/{studentID}/transactions	List student transactions
GET	/students/{studentID}/eligible-plans/{termID}	Get eligible payment plans
POST	/students/{studentID}/enroll-plan	Enroll student in payment plan
GET	/students/{studentID}/payment-schedule	Get student payment schedule
GET	/students/{studentID}/upfront-discount/{termID}	Get upfront discount for term
GET	/students/{studentID}/summary	Get student billing summary
POST	/students/{studentID}/calculate	Calculate billing for student
GET	/students/{studentID}/statement	Get student billing statement

Enrollments (Payment Plan)

Method	Endpoint	Description
GET	/enrollments	List payment plan enrollments
GET	/enrollments/{enrollmentID}	Get enrollment details

---

Settings

List Settings

GET /api/v1/billing/settings

Returns all billing settings.

Success Response (200 OK)

{
  "count": 3,
  "results": [
    {
      "setting_id": 1,
      "setting_key": "DEFAULT_CURRENCY",
      "setting_value": "USD",
      "description": "Default currency for billing"
    }
  ]
}

TypeScript Types

interface BillingSetting {
  setting_id: number
  setting_key: string
  setting_value: string
  description: string | null
}

---

Create Setting

POST /api/v1/billing/settings

Request Body

Field	Type	Required	Description
setting_key	string	Yes	Unique key (max 100)
setting_value	string	Yes	Setting value
description	string	No	Description (max 500)

---

Update Setting

PATCH /api/v1/billing/settings/{settingID}

Request Body

Field	Type	Required	Description
setting_value	string	No	Updated value
description	string	No	Updated description

---

Billing Methods

List Methods

GET /api/v1/billing/methods

Returns all billing methods.

Success Response (200 OK)

{
  "count": 3,
  "results": [
    {
      "method_id": 1,
      "method_code": "UNDERGRAD_PERCREDIT",
      "name": "Undergraduate Per Credit",
      "description": "Standard per-credit billing for undergraduates",
      "method_type": "PER_CREDIT",
      "is_default": true,
      "is_active": true
    }
  ]
}

TypeScript Types

interface BillingMethod {
  method_id: number
  method_code: string
  name: string
  description: string | null
  method_type: 'PER_CREDIT' | 'FLAT_RATE' | 'BANDED' | 'CUSTOM'
  is_default: boolean
  is_active: boolean
}

interface BillingMethodDetail extends BillingMethod {
  created_at: string
  updated_at: string
  configs: BillingMethodConfig[]
}

interface BillingMethodConfig {
  config_id: number
  method_id: number
  config_key: string
  config_value: string
}

---

Get Method

GET /api/v1/billing/methods/{methodID}

Returns method details including configs.

Success Response (200 OK)

{
  "method_id": 1,
  "method_code": "UNDERGRAD_PERCREDIT",
  "name": "Undergraduate Per Credit",
  "method_type": "PER_CREDIT",
  "is_default": true,
  "is_active": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "configs": [
    {
      "config_id": 1,
      "method_id": 1,
      "config_key": "base_rate",
      "config_value": "500.00"
    }
  ]
}

---

Create Method

POST /api/v1/billing/methods

Request Body

Field	Type	Required	Description
method_code	string	Yes	Unique code (max 50)
name	string	Yes	Display name (max 200)
description	string	No	Description (max 500)
method_type	string	Yes	One of: PER_CREDIT, FLAT_RATE, BANDED, CUSTOM
is_default	boolean	No	Default method flag
is_active	boolean	No	Active status

---

Method Sub-resources

List Method Configs

GET /api/v1/billing/methods/{methodID}/configs

Create Method Config

POST /api/v1/billing/methods/{methodID}/configs

Field	Type	Required	Description
method_id	integer	Yes	Parent method ID
config_key	string	Yes	Config key (max 100)
config_value	string	Yes	Config value

List Method Bands

GET /api/v1/billing/methods/{methodID}/bands

Create Method Band

POST /api/v1/billing/methods/{methodID}/bands

Field	Type	Required	Description
method_id	integer	Yes	Parent method ID
term_id	integer	No	Optional term filter
residency_id	integer	No	Optional residency filter
degree_level_id	integer	No	Optional degree level filter
min_credits	decimal	Yes	Minimum credits
max_credits	decimal	Yes	Maximum credits
flat_amount	decimal	Yes	Flat amount for band
per_credit_overage	decimal	No	Per-credit rate above max
is_active	boolean	No	Active status

List Method Credit Rates

GET /api/v1/billing/methods/{methodID}/credit_rates

Create Method Credit Rate

POST /api/v1/billing/methods/{methodID}/credit_rates

Field	Type	Required	Description
term_id	integer	Yes	Term ID
method_id	integer	Yes	Method ID
residency_id	integer	No	Optional residency filter
degree_level_id	integer	No	Optional degree level filter
rate_per_credit	decimal	Yes	Rate per credit hour
effective_date	datetime	Yes	Effective date
is_active	boolean	No	Active status

---

TypeScript Types (Bands & Credit Rates)

interface BillingBand {
  band_id: number
  method_id: number
  term_id: number | null
  residency_id: number | null
  degree_level_id: number | null
  min_credits: string
  max_credits: string
  flat_amount: string
  per_credit_overage: string
  is_active: boolean
}

interface CreditRateSchedule {
  rate_id: number
  term_id: number
  method_id: number
  method_name: string
  residency_id: number | null
  degree_level_id: number | null
  rate_per_credit: string
  effective_date: string
  is_active: boolean
}

---

Fee Types

List Fee Types

GET /api/v1/billing/fee-types

Success Response (200 OK)

{
  "count": 10,
  "results": [
    {
      "fee_type_id": 1,
      "fee_code": "TUITION",
      "name": "Tuition",
      "description": "Standard tuition charge",
      "fee_category": "TUITION",
      "gl_account": "40-1000-1001",
      "is_refundable": true,
      "is_active": true
    }
  ]
}

TypeScript Types

interface FeeType {
  fee_type_id: number
  fee_code: string
  name: string
  description: string | null
  fee_category: 'TUITION' | 'COURSE_FEE' | 'LAB_FEE' | 'STUDENT_FEE' | 'OTHER'
  gl_account: string | null
  is_refundable: boolean
  is_active: boolean
}

---

Create Fee Type

POST /api/v1/billing/fee-types

Request Body

Field	Type	Required	Description
fee_code	string	Yes	Unique code (max 50)
name	string	Yes	Display name (max 200)
description	string	No	Description (max 500)
fee_category	string	Yes	One of: TUITION, COURSE_FEE, LAB_FEE, STUDENT_FEE, OTHER
gl_account	string	No	GL account code (max 50)
is_refundable	boolean	No	Whether fee is refundable
is_active	boolean	No	Active status

---

Term Fees

List Term Fees

GET /api/v1/billing/term-fees

Success Response (200 OK)

{
  "count": 25,
  "results": [
    {
      "term_fee_id": 1,
      "term_id": 10,
      "fee_type_id": 1,
      "fee_type_name": "Tuition",
      "amount": "500.00",
      "is_per_credit": true,
      "residency_id": null,
      "degree_level_id": null,
      "is_active": true
    }
  ]
}

TypeScript Types

interface TermFee {
  term_fee_id: number
  term_id: number
  fee_type_id: number
  fee_type_name: string
  amount: string
  is_per_credit: boolean
  residency_id: number | null
  degree_level_id: number | null
  is_active: boolean
}

interface TermFeeBand {
  band_id: number
  term_fee_id: number
  min_credits: string
  max_credits: string
  amount: string
}

interface TermFeeCategory {
  category_id: number
  term_id: number
  name: string
  description: string | null
  is_active: boolean
}

interface TermFeeCategoryBand {
  id: number
  category_id: number
  min_credits: string
  max_credits: string
  amount: string
}

---

Create Term Fee

POST /api/v1/billing/term-fees

Request Body

Field	Type	Required	Description
term_id	integer	Yes	Term ID
fee_type_id	integer	Yes	Fee type ID
amount	decimal	Yes	Fee amount
is_per_credit	boolean	No	Per-credit fee
residency_id	integer	No	Residency filter
degree_level_id	integer	No	Degree level filter
is_active	boolean	No	Active status

---

Payment Plans

List Payment Plans

GET /api/v1/billing/payment-plans

Success Response (200 OK)

{
  "count": 3,
  "results": [
    {
      "plan_id": 1,
      "plan_code": "MONTHLY4",
      "name": "4-Month Payment Plan",
      "description": "Split tuition over 4 monthly installments",
      "number_of_installments": 4,
      "down_payment_percentage": "25.00",
      "is_active": true
    }
  ]
}

---

Get Payment Plan

GET /api/v1/billing/payment-plans/{planID}

Returns full details including terms, eligibility rules, fees, and schedules.

Success Response (200 OK)

{
  "plan_id": 1,
  "plan_code": "MONTHLY4",
  "name": "4-Month Payment Plan",
  "number_of_installments": 4,
  "down_payment_percentage": "25.00",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "terms": [
    {
      "id": 1,
      "plan_id": 1,
      "term_id": 10,
      "enrollment_deadline": "2024-08-15T00:00:00Z"
    }
  ],
  "eligibility": [
    {
      "id": 1,
      "plan_id": 1,
      "residency_id": null,
      "student_type_id": null,
      "min_credits": "12.00",
      "max_credits": null
    }
  ],
  "fees": [
    {
      "fee_id": 1,
      "plan_id": 1,
      "fee_type_id": 5,
      "fee_type_name": "Payment Plan Fee",
      "amount": "50.00",
      "is_per_installment": false
    }
  ],
  "schedules": [
    {
      "schedule_id": 1,
      "plan_id": 1,
      "installment_number": 1,
      "due_date_offset_days": 0,
      "percentage_of_balance": "25.00"
    }
  ]
}

TypeScript Types

interface PaymentPlan {
  plan_id: number
  plan_code: string
  name: string
  description: string | null
  number_of_installments: number
  down_payment_percentage: string
  is_active: boolean
}

interface PaymentPlanDetail extends PaymentPlan {
  created_at: string
  updated_at: string
  terms: PaymentPlanTerm[]
  eligibility: PaymentPlanEligibility[]
  fees: PaymentPlanFee[]
  schedules: PaymentPlanSchedule[]
}

interface PaymentPlanTerm {
  id: number
  plan_id: number
  term_id: number
  enrollment_deadline: string
}

interface PaymentPlanEligibility {
  id: number
  plan_id: number
  residency_id: number | null
  student_type_id: number | null
  min_credits: string | null
  max_credits: string | null
}

interface PaymentPlanFee {
  fee_id: number
  plan_id: number
  fee_type_id: number
  fee_type_name: string
  amount: string
  is_per_installment: boolean
}

interface PaymentPlanSchedule {
  schedule_id: number
  plan_id: number
  installment_number: number
  due_date_offset_days: number
  percentage_of_balance: string
}

---

Create Payment Plan

POST /api/v1/billing/payment-plans

Request Body

Field	Type	Required	Description
plan_code	string	Yes	Unique code (max 50)
name	string	Yes	Display name (max 200)
description	string	No	Description (max 500)
number_of_installments	integer	Yes	Number of installments (>= 1)
down_payment_percentage	decimal	No	Down payment as percentage
is_active	boolean	No	Active status

---

Upfront Discounts

List Upfront Discounts

GET /api/v1/billing/upfront-discounts

Success Response (200 OK)

{
  "count": 2,
  "results": [
    {
      "discount_id": 1,
      "term_id": 10,
      "name": "Early Payment Discount",
      "discount_percentage": "5.00",
      "deadline": "2024-07-01T00:00:00Z",
      "is_active": true
    }
  ]
}

TypeScript Types

interface UpfrontPaymentDiscount {
  discount_id: number
  term_id: number
  name: string
  discount_percentage: string
  deadline: string
  is_active: boolean
}

---

Create Upfront Discount

POST /api/v1/billing/upfront-discounts

Request Body

Field	Type	Required	Description
term_id	integer	Yes	Term ID
name	string	Yes	Discount name (max 200)
discount_percentage	decimal	Yes	Discount percentage
deadline	datetime	Yes	Deadline for discount
is_active	boolean	No	Active status

---

Transactions

List Transactions

GET /api/v1/billing/transactions

Success Response (200 OK)

{
  "count": 100,
  "results": [
    {
      "transaction_id": 1,
      "student_id": 42,
      "term_id": 10,
      "transaction_type": "CHARGE",
      "transaction_date": "2024-08-01T00:00:00Z",
      "amount": "5000.00",
      "description": "Fall 2024 Tuition",
      "reference_number": "INV-2024-001",
      "fee_type_id": 1,
      "fee_type_name": "Tuition",
      "status_id": 1,
      "created_by": "admin",
      "created_at": "2024-08-01T00:00:00Z"
    }
  ]
}

TypeScript Types

interface Transaction {
  transaction_id: number
  student_id: number
  term_id: number
  transaction_type: 'CHARGE' | 'PAYMENT' | 'CREDIT' | 'REFUND' | 'ADJUSTMENT'
  transaction_date: string
  amount: string
  description: string
  reference_number: string | null
  fee_type_id: number | null
  fee_type_name: string
  status_id: number
  created_by: string | null
  created_at: string
}

interface TransactionDetail extends Transaction {
  updated_by: string | null
  updated_at: string
  items: BillingTransactionItem[]
}

interface BillingTransactionItem {
  item_id: number
  transaction_id: number
  description: string
  amount: string
  fee_type_id: number | null
  enrollment_id: number | null
  gl_account: string | null
}

---

Create Transaction

POST /api/v1/billing/transactions

Request Body

Field	Type	Required	Description
student_id	integer	Yes	Student ID
term_id	integer	Yes	Term ID
transaction_type	string	Yes	One of: CHARGE, PAYMENT, CREDIT, REFUND, ADJUSTMENT
transaction_date	datetime	Yes	Transaction date
amount	decimal	Yes	Amount
description	string	Yes	Description (max 500)
reference_number	string	No	Reference number (max 100)
fee_type_id	integer	No	Fee type ID
status_id	integer	Yes	Status lookup ID
items	array	No	Line items

Transaction Item Fields

Field	Type	Required	Description
description	string	Yes	Item description (max 500)
amount	decimal	Yes	Item amount
fee_type_id	integer	No	Fee type ID
enrollment_id	integer	No	Related enrollment ID
gl_account	string	No	GL account code (max 50)

---

Refund Schedules

List Refund Schedules

GET /api/v1/billing/refund-schedules

Success Response (200 OK)

{
  "count": 2,
  "results": [
    {
      "schedule_id": 1,
      "name": "Standard Refund Schedule",
      "term_id": null,
      "is_default": true,
      "is_active": true
    }
  ]
}

---

Get Refund Schedule

GET /api/v1/billing/refund-schedules/{scheduleID}

Returns schedule details including entries.

Success Response (200 OK)

{
  "schedule_id": 1,
  "name": "Standard Refund Schedule",
  "term_id": null,
  "is_default": true,
  "is_active": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "entries": [
    {
      "entry_id": 1,
      "schedule_id": 1,
      "start_day": 1,
      "end_day": 7,
      "refund_percentage": "100.00"
    },
    {
      "entry_id": 2,
      "schedule_id": 1,
      "start_day": 8,
      "end_day": 14,
      "refund_percentage": "75.00"
    },
    {
      "entry_id": 3,
      "schedule_id": 1,
      "start_day": 15,
      "end_day": null,
      "refund_percentage": "0.00"
    }
  ]
}

TypeScript Types

interface RefundSchedule {
  schedule_id: number
  name: string
  term_id: number | null
  is_default: boolean
  is_active: boolean
}

interface RefundScheduleDetail extends RefundSchedule {
  created_at: string
  updated_at: string
  entries: RefundScheduleEntry[]
}

interface RefundScheduleEntry {
  entry_id: number
  schedule_id: number
  start_day: number
  end_day: number | null
  refund_percentage: string
}

---

Create Refund Schedule

POST /api/v1/billing/refund-schedules

Request Body

Field	Type	Required	Description
name	string	Yes	Schedule name (max 200)
term_id	integer	No	Optional term-specific schedule
is_default	boolean	No	Default schedule flag
is_active	boolean	No	Active status

---

Create Schedule Entry

POST /api/v1/billing/refund-schedules/{scheduleID}/entries

Request Body

Field	Type	Required	Description
schedule_id	integer	Yes	Parent schedule ID
start_day	integer	Yes	Start day (>= 0)
end_day	integer	No	End day (null = no limit)
refund_percentage	decimal	Yes	Refund percentage

---

Student Billing

Get Student Balance

GET /api/v1/billing/students/{studentID}/balance/{termID}

Get the balance for a student in a specific term.

Success Response (200 OK)

{
  "student_id": 42,
  "term_id": 10,
  "total_charges": "15000.00",
  "total_payments": "10000.00",
  "total_credits": "500.00",
  "balance": "4500.00"
}

TypeScript Types

interface StudentBalance {
  student_id: number
  term_id: number
  total_charges: string
  total_payments: string
  total_credits: string
  balance: string
}

---

Get Student Billing Summary

GET /api/v1/billing/students/{studentID}/summary

Get a comprehensive billing summary including transactions and payment plan enrollments.

Success Response (200 OK)

{
  "student_id": 42,
  "term_id": 10,
  "total_charges": "15000.00",
  "total_payments": "10000.00",
  "total_credits": "500.00",
  "balance": "4500.00",
  "transactions": [],
  "payment_plans": []
}

---

Calculate Billing

POST /api/v1/billing/students/{studentID}/calculate

Calculate billing for a student and term.

Request Body

Field	Type	Required	Description
student_id	integer	Yes	Student ID
term_id	integer	Yes	Term ID

Success Response (200 OK)

{
  "student_id": 42,
  "term_id": 10,
  "tuition_charges": "12000.00",
  "fee_charges": "3000.00",
  "total_charges": "15000.00",
  "total_payments": "0.00",
  "total_credits": "0.00",
  "balance": "15000.00",
  "line_items": [
    {
      "description": "Tuition - 15 credits @ $800/credit",
      "category": "TUITION",
      "amount": "12000.00",
      "fee_type_id": 1
    },
    {
      "description": "Student Activity Fee",
      "category": "STUDENT_FEE",
      "amount": "500.00",
      "fee_type_id": 3
    }
  ]
}

TypeScript Types

interface BillingCalculationResult {
  student_id: number
  term_id: number
  tuition_charges: string
  fee_charges: string
  total_charges: string
  total_payments: string
  total_credits: string
  balance: string
  line_items: BillingCalculationItem[]
}

interface BillingCalculationItem {
  description: string
  category: string
  amount: string
  fee_type_id: number | null
}

---

Enroll in Payment Plan

POST /api/v1/billing/students/{studentID}/enroll-plan

Enroll a student in a payment plan.

Request Body

Field	Type	Required	Description
student_id	integer	Yes	Student ID
plan_id	integer	Yes	Payment plan ID
term_id	integer	Yes	Term ID

---

Get Student Payment Schedule

GET /api/v1/billing/students/{studentID}/payment-schedule

Success Response (200 OK)

Returns the student's payment plan enrollment with installment schedule.

---

List Student Transactions

GET /api/v1/billing/students/{studentID}/transactions

Returns all billing transactions for a student.

---

Get Student Statement

GET /api/v1/billing/students/{studentID}/statement

Get a formatted billing statement for a student.

---

Enrollments (Payment Plan)

List Enrollments

GET /api/v1/billing/enrollments

List all payment plan enrollments.

Success Response (200 OK)

{
  "count": 50,
  "results": [
    {
      "enrollment_id": 1,
      "student_id": 42,
      "plan_id": 1,
      "plan_name": "4-Month Payment Plan",
      "term_id": 10,
      "enrolled_date": "2024-07-15T00:00:00Z",
      "total_amount": "15000.00",
      "is_active": true
    }
  ]
}

---

Get Enrollment

GET /api/v1/billing/enrollments/{enrollmentID}

Returns enrollment details including payment schedule.

Success Response (200 OK)

{
  "enrollment_id": 1,
  "student_id": 42,
  "plan_id": 1,
  "plan_name": "4-Month Payment Plan",
  "term_id": 10,
  "enrolled_date": "2024-07-15T00:00:00Z",
  "total_amount": "15000.00",
  "is_active": true,
  "schedules": [
    {
      "schedule_id": 1,
      "enrollment_id": 1,
      "installment_number": 1,
      "due_date": "2024-08-01T00:00:00Z",
      "amount_due": "3750.00",
      "amount_paid": "3750.00",
      "status": "PAID",
      "paid_date": "2024-07-30T00:00:00Z"
    },
    {
      "schedule_id": 2,
      "enrollment_id": 1,
      "installment_number": 2,
      "due_date": "2024-09-01T00:00:00Z",
      "amount_due": "3750.00",
      "amount_paid": "0.00",
      "status": "PENDING",
      "paid_date": null
    }
  ]
}

TypeScript Types

interface StudentPaymentPlanEnrollment {
  enrollment_id: number
  student_id: number
  plan_id: number
  plan_name: string
  term_id: number
  enrolled_date: string
  total_amount: string
  is_active: boolean
}

interface StudentPaymentPlanEnrollmentDetail extends StudentPaymentPlanEnrollment {
  schedules: StudentPaymentPlanSchedule[]
}

interface StudentPaymentPlanSchedule {
  schedule_id: number
  enrollment_id: number
  installment_number: number
  due_date: string
  amount_due: string
  amount_paid: string
  status: 'PENDING' | 'PARTIAL' | 'PAID' | 'OVERDUE'
  paid_date: string | null
}

---

---

---

Complete endpoint reference

Every route this domain registers, with the permission node that gates it. Generated from the route table, so it is complete by construction — the sections above explain behaviour, this one guarantees nothing is missing.

Paths are relative to /api/v1/billing. A node in italics is an exemption rather than a grant: selfservice acts only on the caller's own record, public needs no session at all, and custom carries its own wrapper.

Method	Endpoint	Permission node	Description
GET	/bands	BILLING.FEES	List bands
DELETE	/bands/{bandID}	BILLING.FEES	Delete a band
PATCH	/bands/{bandID}	BILLING.FEES	Update a band
POST	/calculate	BILLING.FEES	Calculate
GET	/class-waivers	BILLING.STUDENT_PLANS	List class waivers
POST	/class-waivers	BILLING.STUDENT_PLANS	Create a class waiver
DELETE	/class-waivers/{waiverID}	BILLING.STUDENT_PLANS	Delete a class waiver
GET	/class-waivers/{waiverID}	BILLING.STUDENT_PLANS	Get one class waiver
PUT	/class-waivers/{waiverID}	BILLING.STUDENT_PLANS	Replace a class waiver
GET	/course-fees	BILLING.COURSE_FEES	List course fees
POST	/course-fees	BILLING.COURSE_FEES	Create a course fee
DELETE	/course-fees/{courseFeeID}	BILLING.COURSE_FEES	Delete a course fee
GET	/course-fees/{courseFeeID}	BILLING.COURSE_FEES	Get one course fee
PUT	/course-fees/{courseFeeID}	BILLING.COURSE_FEES	Replace a course fee
GET	/credit-rates	BILLING.FEES	List credit rates
DELETE	/credit-rates/{rateID}	BILLING.FEES	Delete a credit rate
PATCH	/credit-rates/{rateID}	BILLING.FEES	Update a credit rate
POST	/enroll-payment-plan	STUDENT.MY_BILLING	Create enroll payment plan
GET	/enrollments	RECORDS.STUDENT_FINANCIAL	List enrollments
GET	/enrollments/{enrollmentID}	RECORDS.STUDENT_FINANCIAL	Get one enrollment
GET	/fee-types	BILLING.FEE_TYPES	List fee types
POST	/fee-types	BILLING.FEE_TYPES	Create a fee type
DELETE	/fee-types/{feeTypeID}	BILLING.FEE_TYPES	Delete a fee type
GET	/fee-types/{feeTypeID}	BILLING.FEE_TYPES	Get one fee type
PATCH	/fee-types/{feeTypeID}	BILLING.FEE_TYPES	Update a fee type
DELETE	/housing-assignments/{assignmentID}	BILLING.STUDENT_PLANS	Delete a housing assignment
GET	/housing-plans	BILLING.HOUSING_PLANS	List housing plans
POST	/housing-plans	BILLING.HOUSING_PLANS	Create a housing plan
DELETE	/housing-plans/{housingPlanID}	BILLING.HOUSING_PLANS	Delete a housing plan
GET	/housing-plans/{housingPlanID}	BILLING.HOUSING_PLANS	Get one housing plan
PUT	/housing-plans/{housingPlanID}	BILLING.HOUSING_PLANS	Replace a housing plan
DELETE	/meal-elections/{electionID}	BILLING.STUDENT_PLANS	Delete a meal election
GET	/meal-plans	BILLING.MEAL_PLANS	List meal plans
POST	/meal-plans	BILLING.MEAL_PLANS	Create a meal plan
DELETE	/meal-plans/{mealPlanID}	BILLING.MEAL_PLANS	Delete a meal plan
GET	/meal-plans/{mealPlanID}	BILLING.MEAL_PLANS	Get one meal plan
PUT	/meal-plans/{mealPlanID}	BILLING.MEAL_PLANS	Replace a meal plan
GET	/method-configs	BILLING.RATE_RULES	List method configs
POST	/method-configs	BILLING.RATE_RULES	Create a method config
GET	/method-configs/fields	BILLING.RATE_RULES	List fields
DELETE	/method-configs/{configID}	BILLING.RATE_RULES	Delete a method config
PATCH	/method-configs/{configID}	BILLING.RATE_RULES	Update a method config
GET	/methods	BILLING.METHODS	List methods
POST	/methods	BILLING.METHODS	Create a method
DELETE	/methods/{methodID}	BILLING.METHODS	Delete a method
GET	/methods/{methodID}	BILLING.METHODS	Get one method
PATCH	/methods/{methodID}	BILLING.METHODS	Update a method
GET	/methods/{methodID}/bands	BILLING.METHODS	List the method's bands
POST	/methods/{methodID}/bands	BILLING.METHODS	Add bands to a method
PUT	/methods/{methodID}/bands	BILLING.METHODS	Update the method's bands
GET	/methods/{methodID}/configs	BILLING.METHODS	List the method's configs
POST	/methods/{methodID}/configs	BILLING.METHODS	Add configs to a method
GET	/methods/{methodID}/credit_rates	BILLING.METHODS	List the method's credit rates
POST	/methods/{methodID}/credit_rates	BILLING.METHODS	Add credit rates to a method
GET	/payment-plan-eligibility	BILLING.PLANS	Get payment plan eligibility
DELETE	/payment-plan-eligibility/{eligibilityID}	BILLING.PLANS	Delete a payment plan eligibility
PATCH	/payment-plan-eligibility/{eligibilityID}	BILLING.PLANS	Update a payment plan eligibility
GET	/payment-plan-fees	BILLING.PLANS	List payment plan fees
DELETE	/payment-plan-fees/{feeID}	BILLING.PLANS	Delete a payment plan fee
PATCH	/payment-plan-fees/{feeID}	BILLING.PLANS	Update a payment plan fee
GET	/payment-plan-terms	BILLING.PLANS	List payment plan terms
DELETE	/payment-plan-terms/{termID}	BILLING.PLANS	Delete a payment plan term
PATCH	/payment-plan-terms/{termID}	BILLING.PLANS	Update a payment plan term
GET	/payment-plans	BILLING.PLANS	List payment plans
POST	/payment-plans	BILLING.PLANS	Create a payment plan
DELETE	/payment-plans/{planID}	BILLING.PLANS	Delete a payment plan
GET	/payment-plans/{planID}	BILLING.PLANS	Get one payment plan
PATCH	/payment-plans/{planID}	BILLING.PLANS	Update a payment plan
GET	/payment-plans/{planID}/eligibility	BILLING.PLANS	Get the payment plan's eligibility
POST	/payment-plans/{planID}/eligibility	BILLING.PLANS	Add eligibility to a payment plan
GET	/payment-plans/{planID}/fees	BILLING.PLANS	List the payment plan's fees
POST	/payment-plans/{planID}/fees	BILLING.PLANS	Add fees to a payment plan
GET	/payment-plans/{planID}/terms	BILLING.PLANS	List the payment plan's terms
POST	/payment-plans/{planID}/terms	BILLING.PLANS	Add terms to a payment plan
GET	/program-fees	BILLING.PROGRAM_FEES	List program fees
POST	/program-fees	BILLING.PROGRAM_FEES	Create a program fee
GET	/program-fees/preview-majors	BILLING.PROGRAM_FEES	Preview majors
DELETE	/program-fees/{programFeeID}	BILLING.PROGRAM_FEES	Delete a program fee
GET	/program-fees/{programFeeID}	BILLING.PROGRAM_FEES	Get one program fee
PUT	/program-fees/{programFeeID}	BILLING.PROGRAM_FEES	Replace a program fee
GET	/refund-schedule-entries	BILLING.REFUND_SCHEDULES	List refund schedule entries
DELETE	/refund-schedule-entries/{entryID}	BILLING.REFUND_SCHEDULES	Delete a refund schedule entry
PATCH	/refund-schedule-entries/{entryID}	BILLING.REFUND_SCHEDULES	Update a refund schedule entry
GET	/refund-schedules	BILLING.REFUND_SCHEDULES	List refund schedules
POST	/refund-schedules	BILLING.REFUND_SCHEDULES	Create a refund schedule
DELETE	/refund-schedules/{scheduleID}	BILLING.REFUND_SCHEDULES	Delete a refund schedule
GET	/refund-schedules/{scheduleID}	BILLING.REFUND_SCHEDULES	Get one refund schedule
PATCH	/refund-schedules/{scheduleID}	BILLING.REFUND_SCHEDULES	Update a refund schedule
GET	/refund-schedules/{scheduleID}/entries	BILLING.REFUND_SCHEDULES	List the refund schedule's entries
POST	/refund-schedules/{scheduleID}/entries	BILLING.REFUND_SCHEDULES	Add entries to a refund schedule
GET	/reports/charges	BILLING.REPORT	List charges
GET	/reports/charges/fields	BILLING.REPORT	List fields
GET	/section-fees	BILLING.SECTION_FEES	List section fees
POST	/section-fees	BILLING.SECTION_FEES	Create a section fee
DELETE	/section-fees/{sectionFeeID}	BILLING.SECTION_FEES	Delete a section fee
GET	/section-fees/{sectionFeeID}	BILLING.SECTION_FEES	Get one section fee
PUT	/section-fees/{sectionFeeID}	BILLING.SECTION_FEES	Replace a section fee
GET	/settings	BILLING.FEES	List settings
POST	/settings	BILLING.FEES	Create a setting
DELETE	/settings/{settingID}	BILLING.FEES	Delete a setting
GET	/settings/{settingID}	BILLING.FEES	Get one setting
PATCH	/settings/{settingID}	BILLING.FEES	Update a setting
GET	/student-type-rules	BILLING.STUDENT_TYPE_RULES	List student type rules
POST	/student-type-rules	BILLING.STUDENT_TYPE_RULES	Create a student type rule
GET	/student-type-rules/fields	BILLING.STUDENT_TYPE_RULES	List fields
POST	/student-type-rules/preview	BILLING.STUDENT_TYPE_RULES	Preview
GET	/student-type-rules/score	BILLING.STUDENT_TYPE_RULES	Get score
DELETE	/student-type-rules/{ruleID}	BILLING.STUDENT_TYPE_RULES	Delete a student type rule
GET	/student-type-rules/{ruleID}	BILLING.STUDENT_TYPE_RULES	Get one student type rule
PUT	/student-type-rules/{ruleID}	BILLING.STUDENT_TYPE_RULES	Replace a student type rule
GET	/students/{studentID}/balance/{termID}	RECORDS.STUDENT_FINANCIAL	Get one balance
POST	/students/{studentID}/calculate	BILLING.DETAIL	Calculate for a student
GET	/students/{studentID}/eligible-plans/{termID}	RECORDS.STUDENT_FINANCIAL	Get one eligible plan
POST	/students/{studentID}/enroll-plan	RECORDS.STUDENT_FINANCIAL	Add enroll plan to a student
GET	/students/{studentID}/housing-assignments	BILLING.STUDENT_PLANS	List the student's housing assignments
POST	/students/{studentID}/housing-assignments	BILLING.STUDENT_PLANS	Add housing assignments to a student
GET	/students/{studentID}/meal-elections	BILLING.STUDENT_PLANS	List the student's meal elections
POST	/students/{studentID}/meal-elections	BILLING.STUDENT_PLANS	Add meal elections to a student
GET	/students/{studentID}/payment-plans/{termID}	BILLING.PLANS	Get one payment plan
GET	/students/{studentID}/payment-schedule	RECORDS.STUDENT_FINANCIAL	Get the student's payment schedule
GET	/students/{studentID}/statement	RECORDS.STUDENT_FINANCIAL	Get the student's statement
GET	/students/{studentID}/summary	RECORDS.STUDENT_FINANCIAL	Get the student's summary
GET	/students/{studentID}/transactions	RECORDS.STUDENT_FINANCIAL	List the student's transactions
GET	/students/{studentID}/upfront-discount/{termID}	RECORDS.STUDENT_FINANCIAL	Get one upfront discount
GET	/term-fee-bands	BILLING.FEES	List term fee bands
DELETE	/term-fee-bands/{bandID}	BILLING.FEES	Delete a term fee band
PATCH	/term-fee-bands/{bandID}	BILLING.FEES	Update a term fee band
GET	/term-fee-categories	BILLING.FEES	List term fee categories
DELETE	/term-fee-categories/{categoryID}	BILLING.FEES	Delete a term fee category
PATCH	/term-fee-categories/{categoryID}	BILLING.FEES	Update a term fee category
GET	/term-fee-categories/{categoryID}/bands	BILLING.FEES	List the term fee category's bands
POST	/term-fee-categories/{categoryID}/bands	BILLING.FEES	Add bands to a term fee category
GET	/term-fee-category-bands	BILLING.FEES	List term fee category bands
DELETE	/term-fee-category-bands/{bandID}	BILLING.FEES	Delete a term fee category band
PATCH	/term-fee-category-bands/{bandID}	BILLING.FEES	Update a term fee category band
GET	/term-fees	BILLING.FEES	List term fees
POST	/term-fees	BILLING.FEES	Create a term fee
POST	/term-fees/copy_fees	BILLING.FEES	Copy fees
GET	/term-fees/fields	BILLING.FEES	List fields
DELETE	/term-fees/{termFeeID}	BILLING.FEES	Delete a term fee
GET	/term-fees/{termFeeID}	BILLING.FEES	Get one term fee
PATCH	/term-fees/{termFeeID}	BILLING.FEES	Update a term fee
GET	/term-fees/{termFeeID}/bands	BILLING.FEES	List the term fee's bands
POST	/term-fees/{termFeeID}/bands	BILLING.FEES	Add bands to a term fee
GET	/term-fees/{termFeeID}/categories	BILLING.FEES	List the term fee's categories
POST	/term-fees/{termFeeID}/categories	BILLING.FEES	Add categories to a term fee
GET	/transactions	RECORDS.STUDENT_FINANCIAL	List transactions
POST	/transactions	RECORDS.STUDENT_FINANCIAL	Create a transaction
GET	/transactions/{transactionID}	RECORDS.STUDENT_FINANCIAL	Get one transaction
GET	/upfront-discounts	BILLING.PLANS	List upfront discounts
POST	/upfront-discounts	BILLING.PLANS	Create a upfront discount
DELETE	/upfront-discounts/{discountID}	BILLING.PLANS	Delete a upfront discount
GET	/upfront-discounts/{discountID}	BILLING.PLANS	Get one upfront discount
PATCH	/upfront-discounts/{discountID}	BILLING.PLANS	Update a upfront discount