Period Closing: Lock Accounting Periods in Agatabo

Period closing is the formal act of finalizing a completed accounting period. When you close a period, Agatabo locks every transaction that falls within it, calculates the net income or loss from all income and expense accounts, and creates a PERIOD_CLOSE journal entry that transfers that net result to Retained Earnings. From that point forward, the period’s records are read-only — they can be viewed and reported on, but no one can create, edit, or delete transactions dated within the closed window. This gives your organization an immutable historical record and clear, auditable period boundaries.

You need the periods:close permission to close or undo a period, and reports:read to run the preview. Contact your administrator if you need either permission.

Why Close Periods

Closing periods is not just a bookkeeping formality. It serves several interconnected purposes:

Data integrity. Once closed, no one can accidentally (or deliberately) backdate a transaction into a finalized period. Reports generated from closed periods will always return the same numbers.
Accounting accuracy. The closing entry zeroes out all income and expense accounts and transfers the net balance to Retained Earnings, resetting temporary accounts so the next period starts clean.
Audit compliance. External auditors expect to see period boundaries enforced. A permanent, sequential close history demonstrates that your organization operates proper internal controls.
Operational confidence. Distributed volunteer organizations are especially prone to accidental backdating. Period closing eliminates that risk entirely.

The Closing Workflow

Always preview before you close. The preview endpoint shows you exactly which period will be affected, the net income figure, and any warnings — without touching your data.

Preview the period close

Call the preview endpoint to confirm the period dates and net income figure before committing.

GET /period-closing/preview
Headers:
  x-organization-id: {organizationId}

The response tells you the periodStart, periodEnd, and netProfitLoss, and surfaces any validation warnings you should resolve first. If the system cannot close right now (for example, the current period has not yet ended), canClose returns false along with a reason.

{
  "data": {
    "accountingPeriod": "MONTHLY",
    "periodStart": "2026-06-01T00:00:00.000Z",
    "periodEnd": "2026-06-30T00:00:00.000Z",
    "canClose": true,
    "netProfitLoss": 125000.00,
    "incomeStatement": {
      "totalRevenue": 200000,
      "totalExpenses": 75000,
      "netIncome": 125000
    },
    "validations": {
      "hasWarnings": false,
      "warnings": []
    }
  }
}

Reconcile and verify

Compare the netProfitLoss from the preview against your Profit & Loss report for the same period. Confirm that all deposits, loan payments, and expenses for the period have been posted, and that no DRAFT journal entries remain. Address any items listed in validations.warnings before proceeding.

Get sign-off

Present the preview results to your treasurer, accountant, or management committee. Obtain documented approval — a note in board minutes or a signed closing checklist — before executing the close.

Generate a unique idempotency key

The close endpoint requires an x-idempotency-key header to prevent duplicate closes if a request is retried. Generate a key that uniquely identifies this specific close operation.

const idempotencyKey = `period-close-2026-06-${Date.now()}`;

Execute the period close

POST /period-closing/close
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {idempotencyKey}

A successful response confirms the period dates and provides the ID of the PERIOD_CLOSE journal entry created:

{
  "message": "Accounting period closed successfully",
  "data": {
    "periodStart": "2026-06-01T00:00:00.000Z",
    "periodEnd": "2026-06-30T00:00:00.000Z",
    "accountingPeriod": "MONTHLY",
    "journalEntryId": "je-123",
    "closedAt": "2026-07-05T10:30:00.000Z"
  }
}

Verify and archive

Confirm the response contains both a journalEntryId and a closedAt timestamp. Generate and save your final Balance Sheet and Profit & Loss statement for the closed period. Store these reports alongside the audit log export for the same period.

What Happens Automatically

Period Determination

Agatabo determines which period to close automatically — you do not specify dates manually.

First-ever close: The system identifies the earliest transaction date in your organization (or the organization creation date if no transactions exist) and closes the period that contains it.
Subsequent closes: The system identifies the last closed period’s end date and closes the period immediately following it. Periods must always be closed in strict chronological order — you cannot skip a period.
Current period protection: Agatabo will never close the period that contains today’s date. Only fully elapsed past periods can be closed.

Income and Expense Analysis

For each period close, Agatabo scans all POSTED journal entries (excluding any previous PERIOD_CLOSE entries) within the period’s date range and identifies every INCOME and EXPENSE account with a non-zero net balance.

INCOME accounts:   net balance = credits − debits
EXPENSE accounts:  net balance = debits  − credits

Accounts with a zero net balance are skipped — they require no closing entry.

The PERIOD_CLOSE Journal Entry

Agatabo creates a single balanced journal entry of kind PERIOD_CLOSE, dated at the last moment of the closing period. This entry zeros out every income and expense account and transfers the net result to Retained Earnings:

INCOME accounts (normal credit balance): DEBIT the account to zero it out; CREDIT Retained Earnings.
EXPENSE accounts (normal debit balance): CREDIT the account to zero it out; DEBIT Retained Earnings.

Example — June 2026 with 200,000 RWF revenue and 75,000 RWF expenses:

PERIOD_CLOSE Journal Entry  |  June 30, 2026
─────────────────────────────────────────────────────────
Account                      │   Debit    │   Credit
─────────────────────────────┼────────────┼─────────────
Interest Income              │  200,000   │            ← zeroed out
Operating Expenses           │            │   75,000   ← zeroed out
Retained Earnings            │            │  125,000   ← net income
─────────────────────────────┼────────────┼─────────────
TOTAL                        │  200,000   │  200,000   ✓ balanced

After the entry posts:

Interest Income balance: 0
Operating Expenses balance: 0
Retained Earnings balance: +125,000 RWF

Transaction Lock

Once a period is closed, no transactions dated within that period can be created, edited, or deleted. This lock is enforced at the API level. Any attempt to write a transaction with a date inside a closed period returns a validation error: “Transaction date in closed period.”Plan your closing timeline carefully — post all period entries before you close.

You retain full read access to closed periods. You can view historical transactions, generate reports, export data for audits, and inspect journal entries — you simply cannot modify them.

Sequential Closing Enforcement

Agatabo enforces strict sequential closing. You must close periods in the exact chronological order they occurred.

Scenario	Result
Close January → close February → close March	✅ Allowed
Close January → skip February → close March	❌ Not allowed
Close most recent open period	✅ Allowed

This constraint ensures that Retained Earnings balances carry forward correctly and that financial statements remain consistent across time.

Undoing a Period Close

Use the undo operation sparingly. Frequent undoing signals weak pre-close procedures. Obtain management approval before undoing any period, and document your reason in the audit trail.

When to Undo

Undo a period close only when a material error was discovered that cannot be corrected in the current period — for example, a significant misposted transaction, a bank reconciliation discrepancy, or an auditor-required adjustment. For immaterial errors, the recommended approach is to post a correcting entry in the current open period with a clear description referencing the original error. This is less disruptive and preserves the integrity of the closed period.

Limitations

You can only undo the most recently closed period. If January, February, and March are all closed, you can undo only March.
To undo January, you must first undo March, then February, then January — one at a time, in reverse order.
You cannot undo the same period twice in a row.

How to Undo

POST /period-closing/undo
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {uniqueKey}

Response:

{
  "message": "Latest accounting period close undone successfully",
  "data": {
    "undoneJournalEntryId": "je-123",
    "reversalJournalEntryId": "je-456",
    "periodEnd": "2026-06-30T00:00:00.000Z",
    "undoneAt": "2026-07-08T14:20:00.000Z"
  }
}

Agatabo marks the original PERIOD_CLOSE entry as REVERSED, then creates a new reversal journal entry with the opposite debits and credits. The period reopens immediately — you can now post corrections. After the undo:

Make all required corrections.
Re-run your Profit & Loss and Balance Sheet reports.
Obtain re-approval from management.
Re-close the period following the standard workflow above.

Year-End Closing

Year-end closing in Agatabo is an extension of monthly (or quarterly) closing, not a separate process. Once you have closed every period in the fiscal year, your annual financials are complete.

Close all periods in the fiscal year

For a monthly calendar-year organization, confirm that all twelve periods from January through November have been closed before you close December.

Close the final period

Close December (or the last period of your fiscal year) using the standard workflow. This is your year-end close — Agatabo treats it identically to any other period close.

Generate annual financial statements

After the final close, generate your Balance Sheet as of December 31 and your Profit & Loss for the full year. These are your official annual statements.

GET /reports/balance-sheet?asOfDate=2025-12-31
GET /reports/profit-loss?startDate=2025-01-01&endDate=2025-12-31

Verify Retained Earnings

Confirm that the Retained Earnings balance on the Balance Sheet reflects the accumulated net income from all closed periods in the year. This is your single most important year-end verification.

Complete external audit (if required)

Provide your auditors with the annual financial statements, the audit trail export for the full year, and the closing journal entry for each period as supporting evidence.

Archive all records

Store your financial statements, audit log exports, and closing checklists. Check local regulations — many jurisdictions require financial records to be retained for at least seven years.

Common Errors

"No completed accounting period available to close"

Cause: You are trying to close the current period, which contains today’s date. Agatabo cannot close a period that has not yet ended.Solution: Wait until the period ends (for monthly organizations, until the first day of the next month) and then run the close.

"x-idempotency-key header is required"

Cause: The close or undo request was sent without the required x-idempotency-key header.Solution: Add a unique key to your request. A simple formula is period-close-YYYY-MM-DD-{timestamp}. The key prevents accidental duplicate close operations if a request is retried.

-H "x-idempotency-key: period-close-2026-06-$(date +%s)"

"No closed period available to undo"

Cause: You called the undo endpoint when no periods have been closed yet.Solution: Call GET /period-closing/preview first to confirm the current close state. If no periods are closed, there is nothing to undo.

"Last closed period has already been undone"

Cause: You attempted to undo the same period twice. A period can only be undone once.Solution: The period is already open. Proceed directly to making your corrections and then re-close.

"Transaction date in closed period"

Cause: You are attempting to create, edit, or delete a transaction with a date that falls within an already-closed period. This is the lock enforcement in action.Solution: If the transaction is material and must be dated in the closed period, undo the period close, post the transaction, and re-close. For immaterial corrections, post a correcting entry in the current open period with a descriptive note.

"User is not part of this organization"

Cause: The authenticated user is not a member of the organization specified in the x-organization-id header, or the header contains an incorrect organization ID.Solution: Verify that the x-organization-id header matches your organization’s ID and that the user holds a valid role in that organization.

Audit Trail

Review the audit trail before closing each period to confirm all entries look correct.

Organization Settings

Confirm your accounting period type is configured correctly before your first close.

Permissions

Understand who needs periods:close and how to grant it safely.

Settings Overview

Return to the top-level settings guide.

​Why Close Periods

​The Closing Workflow

​What Happens Automatically

​Period Determination

​Income and Expense Analysis

​The PERIOD_CLOSE Journal Entry

​Transaction Lock

​Sequential Closing Enforcement

​Undoing a Period Close

​When to Undo

​Limitations

​How to Undo

​Year-End Closing

​Common Errors

Audit Trail

Organization Settings

Permissions

Settings Overview

Why Close Periods

The Closing Workflow

What Happens Automatically

Period Determination

Income and Expense Analysis

The PERIOD_CLOSE Journal Entry

Transaction Lock

Sequential Closing Enforcement

Undoing a Period Close

When to Undo

Limitations

How to Undo

Year-End Closing

Common Errors