Business Date

Apache Fineract operates with multiple concepts of "today" simultaneously. Understanding the difference between them is critical for correct loan processing, COB troubleshooting, and integration work.

---

The Four Date Types

Date type	What it represents
Business Date	The logical "today" used for all financial calculations - arrears, accruals, interest, overdue charges
COB Date	Business Date minus one day - represents the day COB last fully processed
Tenant Date	The current wall-clock date adjusted for the tenant's configured timezone
System Date	The server's actual system clock date (UTC by default)

These four dates can differ - and that difference matters.

---

Why Business Date Exists

Before Business Date was introduced (in Fineract v1.8.0), all financial calculations were based on the server's system clock. This caused several problems:

• If a server restarted after midnight but before COB completed, loans could be processed against the wrong date
• Institutions operating across time zones had no reliable way to control when "today" ended for their portfolio
• Recovering from a COB failure meant the system clock had already moved forward, making it impossible to reprocess correctly

Business Date solves this by decoupling the financial date from the system clock. COB explicitly advances Business Date as part of its completion step. No matter what the server clock says, Fineract uses Business Date for all calculations.

---

The Relationship Between Business Date and COB

Business Date and the COB process are tightly coupled:

1. At the end of each COB run, Fineract advances Business Date by one day
2. COB processes loans against the current Business Date (not the system date)
3. COB Date is always Business Date minus one day - it reflects the last day that was fully processed
4. If COB fails mid-run, Business Date is not advanced until COB completes successfully

This means:

• A successfully running system will have Business Date approximately equal to the current Tenant Date
• A system where COB has been failing for three days will have a Business Date three days in the past
• Loan arrears, penalties, and accruals are all based on Business Date, not system time

---

Reading the Current Business Date

GET /fineract-provider/api/v1/businessdate
Authorization: Basic <base64>
Fineract-Platform-TenantId: default

Example response:

{
  "date": [2025, 3, 9],
  "dateFormat": "yyyy-MM-dd",
  "locale": "en",
  "type": {
    "id": 1,
    "code": "businessDateType.BUSINESS_DATE",
    "value": "BUSINESS_DATE"
  }
}

Fetch all date types at once:

GET /fineract-provider/api/v1/businessdate?type=ALL

---

Manually Setting Business Date

Business Date can be set manually via the API. This is useful during:

• Recovery from a failed COB run where the date fell behind
• Testing - simulating future dates to test arrears and penalty behaviour
• Initial setup on a migration - aligning Fineract's business date with the institution's actual operational date

POST /fineract-provider/api/v1/businessdate
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "type": "BUSINESS_DATE",
  "date": "09 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

Production use only when necessary

Manually advancing Business Date in production bypasses COB processing. If you advance Business Date without running COB for the skipped days, loans will not have arrears, penalties, or accruals applied for those days. Only advance manually after verifying COB has completed for all prior dates, or as part of a deliberate recovery procedure.

---

Business Date and Timezone

Each tenant can be configured with its own timezone. Fineract uses the tenant's timezone when determining the Tenant Date, which is used to decide when to trigger COB (so that COB runs at end-of-business for that institution's local day, not UTC midnight).

The timezone is set in the tenant configuration and is applied consistently across:

• COB scheduling (COB triggers based on local end-of-day)
• Date display in API responses
• Business date comparison for arrears and overdue calculations

---

Business Date in COB Processing

The COB run processes loans where the expected payment date is before or equal to Business Date. This is why:

• A loan due "yesterday" (COB Date) is considered overdue from today's perspective
• Interest accrues up to and including Business Date
• The delinquency bucket classification uses the gap between due date and Business Date (not system date)

When Business Date falls behind:

• Loans that became overdue in the gap period are not yet flagged as overdue
• Interest and penalty charges are not applied for the gap days
• Portfolio quality metrics (PAR 30, PAR 90, etc.) are understated

This is why monitoring Business Date lag is an important operational metric. See the Monitoring guide for alert thresholds.

---

Recovery: Business Date Is Behind

If Business Date has fallen behind due to repeated COB failures:

1. Fix the underlying COB failure (see Troubleshooting)
2. Trigger COB manually to process the oldest unprocessed date:

   POST /fineract-provider/api/v1/jobs/Loan COB/inline

3. Business Date advances by one day per successful COB run
4. Repeat until Business Date catches up to the current Tenant Date
5. Monitor each run via the job run history endpoint:

   GET /fineract-provider/api/v1/jobs/{jobId}/runhistory

Do not manually set Business Date to skip days in production - this leaves loans unprocessed for those days.

---

Business Date vs System Date in Integrations

When building integrations or reports against Fineract, always use Business Date as the reference for financial calculations, not new Date() or the system clock.

For example:

• To find loans that became overdue "today", query against Business Date, not the system date
• To check whether a repayment is on time or late, compare the payment date against Business Date at the time of posting
• Reports showing portfolio health should be filtered by Business Date to match what Fineract's own calculations reflect

Fetch Business Date from the API at the start of any batch integration to ensure your external system is aligned with Fineract's current view of "today".