Skip to content

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 nameDPD rangeCounts towards
Current0 daysNot delinquent
1-30 days1 - 30PAR 1
31-60 days31 - 60PAR 1, PAR 30
61-90 days61 - 90PAR 1 to PAR 60
91-180 days91 - 180PAR 1 to PAR 90
181+ days181+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:

  1. Calculates the number of days past due for every active overdue loan
  2. Compares DPD against all configured bucket ranges
  3. Assigns the loan to the highest matching bucket
  4. Records the classification in the m_loan_delinquency_tag_history table
  5. Emits a LoanDelinquencyRangeChangeBusinessEvent business 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/json
json
{
  "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/buckets
json
{
  "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=collection

Every 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_CLASSIFICATION COB step keeps the tags current. Each range change closes the previous tag (sets liftedon_date) and opens a new one, so the row with no liftedon_date is 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;  -- active

This query assumes:

  • m_loan_arrears_aging holds one row per active loan with an unpaid installment past due, and overdue_since_date_derived is the due date of the oldest such installment. The UPDATE_LOAN_ARREARS_AGING COB 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:

LoanDelinquencyRangeChangeBusinessEvent

This 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 LoanDelinquencyRangeChangeBusinessEvent for 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