Fees - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and the accounting integration's developers (for the read-only vocabulary the accounting API mirrors). Scope: Admin (/api/fees/**) and mobile portal (/api/mobile/fees/**) routes owned by the fee management module. The accounting-facing /api/integration/fees/** surface is documented in the integration module's API doc; this page cross-references it where the same data appears.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Catalogue

Structures

Scholarships and Charges

Identical 13-route shape under /api/fees/scholarships (FeeScholarships_*, FeeScholarshipAssignments_*) and /api/fees/charges (FeeCharges_*, FeeChargeAssignments_*):

Obligations

Runs

Payments, mappings, sync

FeeMappingsController and FeeSyncEventsController both carry @RequiresAccountingIntegration() at the class level, so every route above from student-mappings through sync-events/:id/resolve — reads included — answers 404 ACCOUNTING_INTEGRATION_DISABLED while the school's ACCOUNTING_INTEGRATION_ENABLED switch is off, checked after JwtAuthGuard/RoleGuard so an unauthenticated or unauthorised caller still gets 401/403 first. See the integration module's docs for the switch itself.

Reports and settings

Mobile portal (/api/mobile/fees, MOBILE_CHILDREN only — never in ADMIN_MODULES)

Every route above resolves at /api/... — no version segment (URI versioning is enabled but no controller declares one). Every controller declares @Controller("fees") or @Controller("fees/...") under FeesModule, or @Controller("fees") under FeePortalModule mounted at /api/mobile.

5. Auth, Identity, and Permissions

6. DTO and Model Reference

6.1 FeeStudentFeeSummaryDto / FeeStudentFeeDto (obligation)

6.2 CreateAdjustmentDto / CreateWaiverDto

6.3 CreateModifierDto (scholarship/charge)

6.4 AssignStudentsDto

6.5 ListStudentFeesQueryDto

Extends QueryDto. Sort whitelist: dueDate, netPaisa, balancePaisa, studentName, period, updatedAt. Filters: academicSessionId, periodId, studentId, lifecycle, paymentStatus, gradeId, sectionId, search (name/student code), overdue (boolean). pagination=false is REFUSED (PAGINATION_LIMIT_INVALID) — a roll of every child's fee is never returned unpaginated.

6.6 FeePortalFeeDto / FeePortalFeeListDto (portal)

Same shape as the admin summary DTO with everything internal removed: no reason, no createdBy, no actor identity, no manual-line detail beyond amount and label.

FeePortalFeeSummaryDto (each item of fees):

FeePortalFeeListDto is { totals: { netPaisa, paidPaisa, balancePaisa, overdueBalancePaisa }, fees: FeePortalFeeSummaryDto[] }. FeePortalFeeDto adds grossPaisa, scholarshipPaisa, chargePaisa, adjustmentPaisa, waiverPaisa, lines and payments.

6.7 FeePaymentEntryDto / FeePortalPaymentDto (payment entries)

FeePaymentEntryDto (admin: the payments of GET /api/fees/student-fees/:id, each item of GET /api/fees/payments, and the entry of record/reverse/correct results):

FeePaymentListItemDto adds studentFeeId, student, period, academicSessionId and externalTransactionRef.

FeePortalPaymentDto (the payments of a portal fee detail): id (the entry's public id), paidOn, amountPaisa, kind, sourceLabel (School office | Accounting system), reference (office entries only; always null for an external entry) and receiptAvailable (as above, for this caller: it is true only for an entry the receipt route would serve to the same pupil or guardian).

7. Enum Reference

8. Endpoint Reference (representative)

8.1 POST /api/fees/generation-runs

Purpose

Launches a bulk fee generation over a scope (one or more periods, optionally filtered by grade/section/student). Returns immediately with a queued run; the actual per-student work happens in the background via FeeJob.GENERATION_PLAN/GENERATION_CHUNK.

Auth and Permissions

• Auth: JWT
• Guard chain: JwtAuthGuard, RoleGuard
• Permission: StudentFees_CREATE
• Idempotency: requestKey — a repeated request with the same key returns the original run

Request

{
  "kind": "generate",
  "academicSessionId": "0199a3b2-...",
  "periodIds": ["0199a3b2-..."],
  "gradeId": null,
  "sectionId": null,
  "studentIds": null,
  "requestKey": "generate-2083-07"
}

Response

{
  "message": "Generation run queued.",
  "data": {
    "id": "0199a3b2-...",
    "kind": "generate",
    "status": "queued",
    "totalItems": 0,
    "succeededItems": 0,
    "skippedItems": 0,
    "failedItems": 0
  }
}

Side Effects

Database write (fee_generation_runs), outbox enqueue (GENERATION_PLAN), and eventually every item's obligation write, change-feed events, and family/admin notifications.

Error Cases

8.2 POST /api/fees/student-fees/:id/adjustments

Purpose

Records a manual adjustment (any non-zero signed amount) on an obligation — used for corrections the automatic calculation cannot express.

Request

{ "amountPaisa": -5000, "label": "Sibling discount", "reason": "Second child in the family, per office policy", "version": 3 }

Response

The full FeeStudentFeeDto, recalculated totals included.

Error Cases

8.3 POST /api/fees/student-fees/:id/cancel

Purpose

Cancels an obligation nothing has been paid on, releasing its charge-once lines and freeing the (student, period) slot for a later reissue.

Request

{ "reason": "Withdrawn mid-term, no payments recorded", "version": 2 }

Error Cases

8.4 POST /api/fees/{scholarships,charges}/:id/apply

Purpose

Applies a rule-mode modifier to the population a prior eligibility-preview call showed, after office confirmation.

Request

{ "confirm": true, "expectedCount": 42, "version": 1 }

Error Cases

8.5 GET /api/mobile/fees/me

Purpose

The pupil's own fee list — the family-facing surface with every internal field removed.

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard
• Permission: MyFees_READ
• Additional: assertPortalAudience(actor, "student") inside the service

Response

{
  "message": "Fees fetched.",
  "data": {
    "items": [
      { "id": "0199a3b2-...", "period": { "bsYear": 2083, "bsMonth": 7 }, "netPaisa": 580000, "paidPaisa": 300000, "balancePaisa": 280000, "paymentStatus": "partially_paid", "dueDate": { "date": "2026-11-10", "bs": "2083-07-24" } }
    ]
  }
}

8.6 Payment receipts

Purpose

Streams the receipt PDF the accounting application issued for a payment it reported. The school keeps no copy: each request fetches the PDF from accounting and relays the bytes.

Request

paymentId (and studentId) are uuids; a non-uuid is a 400 from ParseUUIDPipe. No body, no query. Each route is rate-limited per account (RATE_LIMITS.FEE_RECEIPT_DOWNLOAD) and per address.

Response

200 with the PDF bytes (not the ResponseDto envelope) and headers the school builds itself:

No header the accounting application sent is forwarded.

When a receipt exists

An entry has a receipt when all of these hold, by the same rule that sets receiptAvailable: it is a payment entry from the accounting application (source = external); its transaction is applied, has applied money and belongs to the integration client named by ACCOUNTING_INTEGRATION_CLIENT_ID; the transaction's external_ref is a uuid (the accounting receipt id); its fee is not cancelled; and no sync event of the transaction matched a student other than the fee's own. Several payment entries of one transaction share one receipt.

Receipt download is active only when ACCOUNTING_INTEGRATION_ENABLED is true and ACCOUNTING_API_URL, ACCOUNTING_API_TOKEN and ACCOUNTING_INTEGRATION_CLIENT_ID are all set. Otherwise every receipt route answers 404 FEE_RECEIPT_NOT_AVAILABLE and receiptAvailable is false everywhere.

Error Cases

A client should not request a receipt when receiptAvailable is false, and may retry a 503 later.

9. Flow Diagrams

9.1 Route Ownership

9.2 Error Decision Tree (a versioned write)

10. Pagination, Sorting, Filtering, and Search

11. Caching, Jobs, and External Integrations

12. Permission Reference

The fee permission modules (packages/db/src/authorization/permission-catalog.ts). None is part of the automatic admin grant except the general catalogue/structure/modifier/obligation/payment/sync/settings read-and-operate set; six are SUPERADMIN_ONLY_MODULES and must be granted to a named role:

13. Error Code Reference (FEE_*)

Every code below is a literal member of ErrorCodes in apps/api/src/common/types/error-codes.ts.

The receipt routes also answer ACCOUNTING_RECEIPT_UNAVAILABLE (503): accounting did not return a usable PDF (§8.6).

14. Zero-Omission API Checklist

• Every controller route is documented (§4).
• Every DTO field, enum, and default is documented (§6, §7).
• Every permission module and its superadmin-only status is documented (§12).
• Every FEE_* error code is documented (§13).
• Representative endpoints carry full request/response/error detail (§8).
• Route ownership, sequence, and error-decision diagrams are included (§9).
• Pagination behavior per list endpoint is documented (§10).
• The doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/fees/backend
• Features and flows doc: /docs/developer/fees/feature