Appearance
Delinquency Bucketing
A delinquency bucket is a band of days past due (DPD), such as 1-30 or 31-60 days, used to group overdue loans by how late their repayments are. Lenders report portfolio risk by bucket: PAR 30, for example, is the share of outstanding principal in loans that are 30 or more days past due.
In Apache Fineract each band is called a delinquency range, and a delinquency bucket is the set of ranges you assign to a loan product. Fineract counts the days past due of every overdue loan and refreshes the classification automatically.
Buckets drive portfolio risk reporting (PAR metrics), automated charge triggers, and business event signals for collections workflows.
What Is a Delinquency Bucket?
A delinquency bucket is a named range of days-past-due (DPD). Common examples:
| Bucket name | DPD range | Counts towards |
|---|---|---|
| Current | 0 days | Not delinquent |
| 1-30 days | 1 - 30 | PAR 1 |
| 31-60 days | 31 - 60 | PAR 1, PAR 30 |
| 61-90 days | 61 - 90 | PAR 1 to PAR 60 |
| 91-180 days | 91 - 180 | PAR 1 to PAR 90 |
| 181+ days | 181+ | PAR 1 to PAR 180; write-off risk |
PAR figures are cumulative, not one bucket each: PAR 30 covers every loan 30 or more days past due. With the ranges above that is the 31-60 bucket and every bucket after it, plus loans at exactly 30 days, which sit in the 1-30 bucket (and likewise for PAR 60, 90 and 180). If you want bucket totals to add up to PAR figures exactly, start each range at the PAR threshold, for example 30-59 instead of 31-60.
The ranges, names, and number of buckets are fully configurable. An institution might define six buckets or twenty - depending on their portfolio management and regulatory reporting requirements.
How Bucket Classification Works
Classification runs automatically during COB (Close of Business). Each night, Fineract:
- Calculates the number of days past due for every active overdue loan
- Compares DPD against all configured bucket ranges
- Assigns the loan to the highest matching bucket
- Records the classification in the
m_loan_delinquency_tag_historytable - Emits a
LoanDelinquencyRangeChangeBusinessEventbusiness event if the bucket changed since the last run
Bucket assignment is updated every night. A loan that moves from the 1-30 bucket to the 31-60 bucket (because it remained unpaid for another month) is reclassified automatically on the COB run that crosses the threshold.
Days past due are counted from the installment due dates on the repayment schedule, including any dates moved by your holiday and working-day rules. Because classification depends on COB, a failed or stuck COB run leaves buckets stale; Monitoring & Observability shows how to watch the COB jobs.
Creating a Delinquency Bucket Configuration
Step 1: Create Individual Ranges
bash
POST /fineract-provider/api/v1/delinquency/ranges
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/jsonjson
{
"classification": "1 to 30 days",
"minimumAgeDays": 1,
"maximumAgeDays": 30,
"locale": "en"
}Create one range per bucket tier. For the highest tier (open-ended), omit maximumAgeDays or set it to a very large number:
json
{
"classification": "181+ days",
"minimumAgeDays": 181,
"locale": "en"
}Step 2: Create a Delinquency Bucket
A bucket is a named collection of ranges:
bash
POST /fineract-provider/api/v1/delinquency/bucketsjson
{
"name": "Standard Delinquency Bucket",
"ranges": [1, 2, 3, 4, 5]
}The ranges array contains the IDs of the ranges created in Step 1.
Step 3: Assign the Bucket to a Loan Product
bash
PUT /fineract-provider/api/v1/loanproducts/{productId}json
{
"delinquencyBucketId": 1
}All loans created from this product will be classified using the assigned bucket.
Reading Delinquency Classification
On a single loan
bash
GET /fineract-provider/api/v1/loans/{loanId}?associations=collectionEvery loan read returns the current range in delinquencyRange; the collection association adds a delinquent object with the delinquency figures. An excerpt of the response:
json
{
"delinquencyRange": {
"id": 2,
"classification": "31 to 60 days",
"minimumAgeDays": 31,
"maximumAgeDays": 60
},
"delinquent": {
"delinquentDate": "2025-01-15",
"delinquentDays": 52,
"delinquentAmount": 1250.00,
"installmentLevelDelinquency": [
{
"rangeId": 2,
"classification": "31 to 60 days",
"delinquentAmount": 1250.00
}
]
}
}The history of a loan's range changes is at GET /fineract-provider/api/v1/loans/{loanId}/delinquencytags: one entry per tag, with delinquencyRange, addedOnDate and liftedOnDate.
Installment-level vs Loan-level delinquency
Fineract supports delinquency tracking at two levels:
- Loan-level - the bucket is determined by the oldest unpaid installment's DPD
- Installment-level - each overdue installment is independently classified into a bucket, allowing a loan to span multiple buckets if it has installments overdue by different amounts of time
Installment-level delinquency gives more granular data for collections prioritisation. Enable it on the loan product with:
json
{
"enableInstallmentLevelDelinquency": true
}Listing All Delinquent Loans
Fineract 1.16.1 has no API filter for loans by delinquency range: GET /fineract-provider/api/v1/loans filters only by externalId, accountNo, clientId and status. For lists and portfolio-level reporting, use the Fineract reporting module or query the database directly:
sql
-- Active loans by their current (loan-level) delinquency range
SELECT
dr.classification AS bucket,
COUNT(*) AS loan_count,
SUM(l.principal_outstanding_derived) AS outstanding_principal
FROM m_loan l
JOIN m_loan_delinquency_tag_history th
ON th.loan_id = l.id
AND th.liftedon_date IS NULL -- the open tag is the current range
JOIN m_delinquency_range dr ON dr.id = th.delinquency_range_id
WHERE l.loan_status_id = 300 -- active
GROUP BY dr.classification, dr.min_age_days
ORDER BY dr.min_age_days;This query assumes:
- The
LOAN_DELINQUENCY_CLASSIFICATIONCOB step keeps the tags current. Each range change closes the previous tag (setsliftedon_date) and opens a new one, so the row with noliftedon_dateis the loan's current range. - Loans that are not delinquent have no open tag and do not appear.
- It counts loan-level ranges only. Installment-level ranges are stored separately, in
m_loan_installment_delinquency_tag. - Figures are as of the last COB run.
PAR (Portfolio at Risk) Calculation
PAR X is the percentage of the outstanding portfolio principal where at least one installment is X or more days past due.
sql
-- PAR 30 as a percentage of active outstanding principal.
-- Replace 2026-10-19 with your business date minus 30 days.
SELECT
100.0 * SUM(CASE WHEN a.overdue_since_date_derived <= DATE '2026-10-19'
THEN l.principal_outstanding_derived ELSE 0 END)
/ NULLIF(SUM(l.principal_outstanding_derived), 0) AS par30_percentage
FROM m_loan l
LEFT JOIN m_loan_arrears_aging a ON a.loan_id = l.id
WHERE l.loan_status_id = 300; -- activeThis query assumes:
m_loan_arrears_agingholds one row per active loan with an unpaid installment past due, andoverdue_since_date_derivedis the due date of the oldest such installment. TheUPDATE_LOAN_ARREARS_AGINGCOB step refreshes it, so the figure is as of the last COB run.- A loan counts towards PAR 30 when that oldest unpaid installment fell due 30 or more days before the business date. Change the cutoff date for PAR 60 or PAR 90.
- The numerator and denominator both use each loan's full outstanding principal (
m_loan.principal_outstanding_derived), not just the overdue part. - Loans with an arrears ageing grace period (
m_loan.grace_on_arrears_ageing) only get a row once an installment is overdue by more than that grace period.
PAR values are always calculated against Business Date (not system date) to stay consistent with Fineract's own view of overdue status.
Business Events for Collections Workflows
Every time a loan moves to a new delinquency bucket, Fineract emits:
LoanDelinquencyRangeChangeBusinessEventThis event contains the loan ID, the previous bucket, the new bucket, and the current DPD. Subscribe to this event via the Kafka or ActiveMQ / JMS connector to:
- Trigger escalation in your collections system
- Send automated SMS or push notifications to borrowers
- Assign the loan to a specialist collections officer
- Update risk scoring in your CRM
See the Business Events guide for connector setup.
Collections work itself can be recorded in Fineract too: field officers post group repayments at meetings with collection sheets, and follow-up visits can be logged in a loan datatable next to the loan.
Example event payload
json
{
"businessEventType": "LoanDelinquencyRangeChangeBusinessEvent",
"loanId": 1234,
"loanExternalId": "LOAN-ABC-001",
"delinquencyRange": {
"id": 3,
"classification": "61 to 90 days"
},
"delinquentDays": 67,
"delinquentDate": "2025-01-15"
}Viewing Configured Buckets and Ranges
bash
# All configured ranges
GET /fineract-provider/api/v1/delinquency/ranges
# All configured buckets
GET /fineract-provider/api/v1/delinquency/buckets
# A specific bucket with its ranges
GET /fineract-provider/api/v1/delinquency/buckets/{bucketId}Best Practices
- Align bucket boundaries with regulatory requirements - many central banks require specific PAR 30/60/90 reporting, so match your bucket ranges to those thresholds
- Use installment-level delinquency for complex products - especially for progressive or multi-tranche loans where individual installments may have very different overdue ages
- Subscribe to
LoanDelinquencyRangeChangeBusinessEventfor real-time collections triggers rather than polling the API nightly - Re-evaluate bucket configuration after portfolio growth - a single bucket covering 1-90 days is fine for small portfolios but obscures risk concentration as volumes grow
Related Guides
- Close of Business (COB) - how the nightly batch run drives delinquency classification
- Business Date - why PAR calculations use Business Date, not system time
- Charges & Penalties - configuring the overdue charges that delinquency triggers
- Progressive Loan Configuration - installment-level delinquency for multi-tranche products
- Business Events - subscribing to
LoanDelinquencyRangeChangeBusinessEventfor collections workflows