Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/muhammadbugaje/gobarau_backend/llms.txt

Use this file to discover all available pages before exploring further.

The Finance module is the central hub for all monetary operations at Gobarau Academy. It covers the full lifecycle of school fees — from defining fee categories and mapping them to class levels, to recording individual student payments with full audit trails. Beyond fees, the module manages scholarship funds and their recipients, and operates a school marketplace where students can request items, backed by inventory tracking and restock history. All write endpoints require authentication; scholarship and restock operations are restricted to admin-level users.

​
Fee Management

​
Fee Types

Fee types are reusable categories (e.g., “Tuition”, “ICT Levy”, “PTA Fee”) that are later assigned amounts via Fee Structures. The code field must be globally unique.

​
GET /api/finance/fee-types/

Returns a list of all fee type definitions. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the fee type.
​
public_id
string (UUID)
Globally unique UUID identifier of the fee type.
​
name
string
Human-readable name of the fee category (e.g., “Tuition Fee”).
​
code
string
Short unique code identifier (max 20 characters), e.g., "TUI".
​
description
string
Optional long-form description of the fee type. Defaults to empty string.
​
is_recurring
boolean
Whether this fee is charged on a recurring basis each term or session.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/finance/fee-types/

Creates a new fee type. Permissions: IsAuthenticated, IsStaffOrAdmin
​
name
string
required
Display name for this fee category. Maximum 200 characters.
​
code
string
required
Short unique code (max 20 characters). Must be unique across all fee types.
​
description
string
Optional description. Defaults to "".
​
is_recurring
boolean
Set to true for fees billed every term/session. Defaults to false.

​
Fee Structures

Fee structures bind a fee type to a specific class level and academic session, with a concrete monetary amount and an optional due date.
The combination of fee_type, class_level, and session must be unique — you cannot define two fee structures for the same fee type in the same class and session.

​
GET /api/finance/fee-structures/

Returns all fee structures across all class levels and sessions. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
fee_type
integer (FK)
ID of the related FeeType.
​
class_level
integer (FK)
ID of the ClassLevel from the administration module.
​
session
integer (FK)
ID of the AcademicSession this structure applies to.
​
amount
string (decimal)
Fee amount, up to 10 digits with 2 decimal places (e.g., "15000.00").
​
due_date
string (date) | null
Optional ISO 8601 date by which the fee should be paid. null if not set.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/finance/fee-structures/

Creates a new fee structure. Permissions: IsAuthenticated, IsStaffOrAdmin
​
fee_type
integer
required
ID of an existing FeeType.
​
class_level
integer
required
ID of the target ClassLevel.
​
session
integer
required
ID of the AcademicSession this amount applies to.
​
amount
string (decimal)
required
Monetary amount charged. e.g., "25000.00".
​
due_date
string (date)
Optional payment deadline in YYYY-MM-DD format.

​
Payments

Payments record individual transactions made by students against a specific fee structure. Every payment must carry a globally unique receipt_number.
The receipt_number field has a unique=True database constraint. Attempting to create two payments with the same receipt number will return a 400 Bad Request validation error.

​
GET /api/finance/payments/

Returns all payment records ordered by most recent payment date. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the payment record.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
student
integer (FK)
ID of the StudentProfile who made the payment.
​
fee_structure
integer (FK)
ID of the FeeStructure this payment is against.
​
amount
string (decimal)
Amount paid in this transaction.
​
payment_date
string (date)
Date the payment was recorded (YYYY-MM-DD).
​
method
string (enum)
Payment method. One of: cash, bank_transfer, online.
​
reference
string
Optional external reference number (e.g., bank teller number). Defaults to "".
​
status
string (enum)
Payment status. One of: pending, paid, partial, overdue, refunded.
​
receipt_number
string
Unique receipt identifier (max 50 characters).
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.
​
created_by
integer (FK) | null
ID of the Person (staff) who created this record (from AuditMixin).
​
updated_by
integer (FK) | null
ID of the Person who last modified this record.

​
POST /api/finance/payments/

Records a new student payment transaction. Permissions: IsAuthenticated, IsStaffOrAdmin
​
student
integer
required
ID of the StudentProfile making the payment.
​
fee_structure
integer
required
ID of the FeeStructure being paid against.
​
amount
string (decimal)
required
Amount paid in this transaction, e.g., "5000.00".
​
payment_date
string (date)
required
Date of payment in YYYY-MM-DD format.
​
method
string (enum)
required
Payment method. Must be one of: cash, bank_transfer, online.
​
receipt_number
string
required
A unique receipt reference. Maximum 50 characters. Must not already exist.
​
reference
string
Optional external reference (e.g., bank slip number). Defaults to "".
​
status
string (enum)
Payment status. Defaults to pending. Options: pending, paid, partial, overdue, refunded.
# Create a new payment record
curl -X POST https://api.gobarauacademy.edu.ng/api/finance/payments/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 42,
    "fee_structure": 7,
    "amount": "15000.00",
    "payment_date": "2025-01-20",
    "method": "bank_transfer",
    "receipt_number": "RCP-2025-00891",
    "reference": "TRF/0123456789",
    "status": "paid"
  }'

​
Scholarships

Scholarship management is restricted to admin-level users only (IsAdminLevel). Staff without admin privileges will receive a 403 Forbidden response.

​
Scholarship Funds

​
GET /api/finance/scholarship-funds/

Returns all scholarship funds available for allocation. Permissions: IsAuthenticated, IsAdminLevel
​
id
integer
Auto-incrementing primary key of the scholarship fund.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
name
string
Name of the scholarship fund (max 200 characters).
​
description
string
Optional description of the fund’s purpose.
​
amount
string (decimal)
Total amount available in the fund.
​
session
integer (FK)
ID of the AcademicSession this fund is allocated for.
​
is_active
boolean
Whether recipients can currently be assigned from this fund.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/finance/scholarship-funds/

Creates a new scholarship fund. Permissions: IsAuthenticated, IsAdminLevel
​
name
string
required
Display name for this scholarship fund.
​
amount
string (decimal)
required
Total monetary value of the fund, e.g., "500000.00".
​
session
integer
required
ID of the AcademicSession this fund belongs to.
​
description
string
Optional description. Defaults to "".
​
is_active
boolean
Defaults to true. Set to false to freeze the fund.

​
Scholarship Recipients

A student may only be awarded a given scholarship once. The combination of student and scholarship is unique — duplicate assignments will fail with a 400 Bad Request.

​
GET /api/finance/scholarship-recipients/

Returns all scholarship recipient records ordered by most recent award date. Permissions: IsAuthenticated, IsAdminLevel
​
id
integer
Auto-incrementing primary key.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
student
integer (FK)
ID of the StudentProfile who received the award.
​
scholarship
integer (FK)
ID of the ScholarshipFund from which the award was drawn.
​
amount_awarded
string (decimal)
Exact amount awarded to this student.
​
awarded_date
string (date)
ISO 8601 date the scholarship was awarded.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.
​
created_by
integer (FK) | null
ID of the staff member who created this record (from AuditMixin).
​
updated_by
integer (FK) | null
ID of the staff member who last modified this record.

​
POST /api/finance/scholarship-recipients/

Awards a scholarship to a student. Permissions: IsAuthenticated, IsAdminLevel
​
student
integer
required
ID of the recipient StudentProfile.
​
scholarship
integer
required
ID of the ScholarshipFund to draw from.
​
amount_awarded
string (decimal)
required
Amount to award, e.g., "50000.00".
​
awarded_date
string (date)
required
Date of award in YYYY-MM-DD format.

​
Marketplace

The school marketplace allows students to request items such as uniforms, stationery, and lab materials. Items are organized by category, tracked with inventory levels, and fulfilled through a request workflow.

​
Item Categories

​
GET /api/finance/item-categories/

Returns all marketplace item categories. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the category.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
name
string
Category name, max 100 characters (e.g., “Stationery”, “Uniform”).
​
description
string
Optional description. Defaults to "".
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/finance/item-categories/

Creates a new item category. Permissions: IsAuthenticated, IsStaffOrAdmin
​
name
string
required
Category name. Maximum 100 characters.
​
description
string
Optional description. Defaults to "".

​
Marketplace Items

​
GET /api/finance/marketplace-items/

Returns all items listed in the school marketplace. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
name
string
Item name (max 200 characters).
​
description
string
Optional item description.
​
category
integer (FK) | null
ID of the associated ItemCategory. Nullable — the category can be removed without deleting the item (SET_NULL).
​
price
string (decimal)
Unit selling price of the item.
​
stock_quantity
integer
Current quantity in stock.
​
is_available
boolean
Whether the item is currently visible and requestable by students.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/finance/marketplace-items/

Adds a new item to the marketplace. Permissions: IsAuthenticated, IsStaffOrAdmin
​
name
string
required
Item name. Maximum 200 characters.
​
price
string (decimal)
required
Unit price, e.g., "1200.00".
​
category
integer
Optional ID of an ItemCategory. Can be null.
​
description
string
Optional item description. Defaults to "".
​
stock_quantity
integer
Initial stock quantity. Defaults to 0.
​
is_available
boolean
Set to false to hide the item from students. Defaults to true.

​
Marketplace Requests

A MarketplaceRequest represents a student’s order. Individual line items (which item, how many, at what price) are stored separately via RequestItem.

​
GET /api/finance/marketplace-requests/

Returns all marketplace requests. The response includes a nested request_items array via MarketplaceRequestSerializer. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key of the request.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
student
integer (FK)
ID of the requesting StudentProfile.
​
request_date
string (date)
Automatically set to today’s date on creation (auto_now_add=True).
​
status
string (enum)
Current status. One of: pending, approved, fulfilled, cancelled.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.
​
request_items
array
Nested list of RequestItem objects associated with this request (read-only).

​
POST /api/finance/marketplace-requests/

Creates a new marketplace request for a student. Permissions: IsAuthenticated, IsStaffOrAdmin
​
student
integer
required
ID of the StudentProfile submitting the request.
​
status
string (enum)
Initial status. Defaults to pending. Options: pending, approved, fulfilled, cancelled.
# Submit a new marketplace request
curl -X POST https://api.gobarauacademy.edu.ng/api/finance/marketplace-requests/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "student": 42,
    "status": "pending"
  }'

​
Request Items

Request items are the individual line items attached to a marketplace request. Each request + item pair must be unique within a single request.
You cannot add the same item to the same request more than once. If a student needs more of an item, increase the quantity on the existing RequestItem instead.

​
GET /api/finance/request-items/

Returns all request line items. Permissions: IsAuthenticated, IsStaffOrAdmin
​
id
integer
Auto-incrementing primary key.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
request
integer (FK)
ID of the parent MarketplaceRequest.
​
item
integer (FK)
ID of the MarketplaceItem being requested.
​
quantity
integer
Number of units. Defaults to 1. Must be a positive integer.
​
unit_price
string (decimal)
Price per unit captured at the time of the request.
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.

​
POST /api/finance/request-items/

Adds a line item to an existing marketplace request. Permissions: IsAuthenticated, IsStaffOrAdmin
​
request
integer
required
ID of an existing MarketplaceRequest.
​
item
integer
required
ID of the MarketplaceItem to request.
​
quantity
integer
required
Number of units to request. Must be ≥ 1.
​
unit_price
string (decimal)
required
Unit price at the time of adding the item, e.g., "1200.00".

​
Restock Logs

Restock logs provide a complete, immutable audit trail every time stock is added to a marketplace item. Creation is restricted to admin-level users.

​
GET /api/finance/restock-logs/

Returns all restock events ordered by most recent first. Permissions: IsAuthenticated, IsAdminLevel
​
id
integer
Auto-incrementing primary key of the restock event.
​
public_id
string (UUID)
Globally unique UUID identifier.
​
item
integer (FK)
ID of the MarketplaceItem that was restocked.
​
quantity_added
integer
Number of units added during this restock event.
​
previous_stock
integer
Stock level before the restock.
​
new_stock
integer
Stock level after the restock.
​
restocked_at
string (ISO 8601 datetime)
Timestamp when the restock was recorded. Set automatically (auto_now_add=True).
​
created_at
string (ISO 8601 datetime)
Timestamp when the record was created.
​
updated_at
string (ISO 8601 datetime)
Timestamp of the last update.
​
created_by
integer (FK) | null
ID of the staff member who created this restock record (from AuditMixin).
​
updated_by
integer (FK) | null
ID of the staff member who last modified this record.

​
POST /api/finance/restock-logs/

Records a new restock event for a marketplace item. Permissions: IsAuthenticated, IsAdminLevel
​
item
integer
required
ID of the MarketplaceItem being restocked.
​
quantity_added
integer
required
Number of units added to stock.
​
previous_stock
integer
required
Stock level before this restock (for audit accuracy).
​
new_stock
integer
required
Resulting stock level after the addition.

Build docs developers (and LLMs) love

Get started for freeTalk to us