Distributing Dividends

Overview

Distributing a dividend pool calculates individual member allocations based on your organization’s distribution method and creates a journal entry that debits retained earnings and credits member savings accounts. This action transitions the pool from draft status to distributed status and is permanent and irreversible.

What happens: Distribution creates a single DIVIDEND_DISTRIBUTION journal entry with one debit to RETAINED_EARNINGS and multiple credits to member SAVINGS accounts. The pool’s journalEntryId is set, permanently marking it as distributed.

Before You Begin

Prerequisites:

You have dividends:write permission
Dividend pool exists in draft status (journalEntryId = null)
Pool period end is on or before the last closed accounting period end
At least one accounting period has been closed
Sufficient retained earnings balance to cover the pool amount
At least one active member (isActive = true) exists

Distribution is permanent and irreversible: Once distributed, the pool cannot be undone, edited, or deleted. The journal entry debits retained earnings and credits member savings accounts immediately. Only distribute when you are certain the pool is correct.

Step-by-Step Instructions

Step 1: Navigate to Pool

Open Dividends section

Click Dividends in the left sidebar

Find draft pool

Locate the pool with status “Draft”

Click on pool

Opens pool details page showing calculated allocations

Step 2: Review Calculated Allocations

Before distributing, verify the automatically calculated member allocations: Check individual amounts:

Review each member’s calculated dividend amount
Verify calculations match your expectations based on distribution method
Ensure no members are unexpectedly excluded

Verify total:

Sum of all member allocations should equal pool total amount
Agatabo handles rounding automatically to ensure exact match

Understand distribution method:

Equal: All active members receive equal shares (or time-weighted if enabled)
By contribution: Members with higher savings contributions receive proportionally larger dividends
Time-weighting (if enabled): Allocations adjusted based on participation days during period

Distribution method is organization-level: The method used (equal vs. by_contribution) and time-weighting setting come from organization dividend settings. All pools use the same distribution rules.

Step 3: Verify Prerequisites

Before distributing, confirm: Accounting period closure:

Pool period end must be on or before last closed accounting period end
At least one accounting period must be closed
Distribution date will default to pool.periodEnd + 1 day (or you can specify a custom date)

Retained earnings:

Retained earnings balance ≥ pool amount
Distribution will debit retained earnings by the full pool amount

Active members:

At least one active member (isActive = true) exists
Only active members receive dividends
Inactive members are automatically excluded from allocations

Validation errors: If prerequisites aren’t met, distribution will fail with specific error messages.

Step 4: Distribute the Pool

Click Distribute

Opens distribution dialog

Set distribution date (optional)

Default: pool.periodEnd + 1 day
Custom: Choose specific date (must be after last closed period end)

Review warning

Dialog warns that distribution is permanent and irreversible

Confirm distribution

Click Confirm to proceed

Step 5: Verify Distribution

After distribution completes:

Check pool status

Status should now be “Distributed” (journalEntryId populated)

Review journal entry

Navigate to General Ledger → Journal Entries
Find DIVIDEND_DISTRIBUTION entry
Verify one debit to RETAINED_EARNINGS and multiple credits to member SAVINGS

Spot-check member balances

Navigate to a few member profiles
Verify SAVINGS account balance increased by dividend amount

Check retained earnings

Navigate to General Ledger → RETAINED_EARNINGS account
Verify balance decreased by pool amount

What Happens During Distribution

When you distribute a dividend pool, Agatabo automatically:

Validates accounting period constraints
- Checks at least one accounting period is closed
- Validates pool.periodEnd ≤ last closed accounting period end
- Validates distribution date > last closed accounting period end
Retrieves organization settings
- Loads distribution method (equal or by_contribution)
- Loads time-weighting setting (enabled or disabled)
Identifies eligible members
- Queries all organization users with isActive = true
- Excludes inactive members from allocations
- Requires at least one active member
Calculates individual allocations
- Equal method: Divides pool amount equally (or by participation days if time-weighted)
- By contribution method: Allocates proportionally based on savings balance (or time-weighted contributions)
- Handles rounding to ensure exact total match
- Filters out zero-amount allocations
Creates single journal entry
- Kind: DIVIDEND_DISTRIBUTION
- One DEBIT line: RETAINED_EARNINGS (pool amount)
- Multiple CREDIT lines: SAVINGS accounts (one per member with non-zero allocation)
- Transaction date: specified date or default (pool.periodEnd + 1 day)
- Idempotency key: prevents duplicate distribution
Updates pool status
- Sets journalEntryId to the created journal entry ID
- Pool status changes from “draft” to “distributed”
- Pool becomes locked (cannot be edited or deleted)
Logs audit trail
- Records who distributed the pool (actorOrganizationUserId)
- Timestamp of distribution
- All journal entry details

Critical: Distribution creates ONE journal entry with multiple lines, not separate journal entries for each member. This ensures the transaction is atomic and balanced.

Distribution Methods

Equal Distribution

All active members receive the same amount (or time-weighted equal shares). Without time-weighting:

Pool: 10,000,000 RWF
Active members: 50
Per member: 10,000,000 ÷ 50 = 200,000 RWF each

With time-weighting:

Pool: 10,000,000 RWF
Period: 90 days (Jan 1 - Mar 31)

Members:
  - Alice: Active all 90 days → 90 participation days
  - Bob: Joined Feb 1, active 60 days → 60 participation days
  - Carol: Left Feb 28, active 59 days → 59 participation days

Total participation days: 209 days

Allocations:
  - Alice: (90 / 209) × 10M = 4,306,220 RWF
  - Bob: (60 / 209) × 10M = 2,870,813 RWF
  - Carol: (59 / 209) × 10M = 2,822,967 RWF

By Contribution Distribution

Members receive dividends proportional to their savings contributions during the period. Without time-weighting:

Pool: 5,000,000 RWF

Member savings balances:
  - Alice: 2,000,000 RWF (40% of total)
  - Bob: 1,500,000 RWF (30% of total)
  - Carol: 1,500,000 RWF (30% of total)
Total: 5,000,000 RWF

Allocations:
  - Alice: 40% × 5M = 2,000,000 RWF
  - Bob: 30% × 5M = 1,500,000 RWF
  - Carol: 30% × 5M = 1,500,000 RWF

With time-weighting: Contributions are weighted by how long funds were held during the period. Recent deposits count less than funds held the entire period.

Distribution Date

The distribution date determines when the journal entry is recorded (transaction date). Default behavior:

If no distribution date specified: pool.periodEnd + 1 day
Example: Pool period Jan 1 - Mar 31 → default distribution date is April 1

Custom date:

You can specify any date after the last closed accounting period end
Cannot be on or before the last closed period end
Typically set to the actual day you’re distributing

Validation:

distributionDate > lastClosedAccountingPeriodEnd

Example:

Pool period: Jan 1 - Mar 31, 2026
Last closed period end: Mar 31, 2026
Valid distribution dates: Apr 1, 2026 or later
Invalid: Mar 31, 2026 or earlier (would fail validation)

Eligibility

Only active members receive dividends. Eligibility criteria:

organizationUser.isActive = true (only requirement)
No minimum savings balance required
No minimum membership duration required

Inactive members:

Automatically excluded from allocations
Do not appear in dividend distribution
Cannot receive dividends even if they have savings

Zero-amount allocations:

If an active member’s calculated allocation is zero (e.g., no savings in by_contribution method), they are excluded from the journal entry
Only members with non-zero allocations receive credits

Common Scenarios

Quarterly Dividend Distribution

Standard quarterly workflow:

Close quarter accounting period

Ensure Q1 2026 (Jan-Mar) accounting period is closed

Create draft pool

Period: 2026-01-01 to 2026-03-31
Amount: Based on profit and dividend policy
Pool starts in draft status

Review allocations

Open pool details and verify calculated member allocations

Distribute

Click Distribute
Default distribution date: 2026-04-01
Confirm permanent action

Verify

Check member SAVINGS accounts increased
Check RETAINED_EARNINGS decreased

Annual Dividend Distribution

Year-end distribution:

Close full year

Ensure all 2026 accounting periods closed

Create draft pool

Period: 2026-01-01 to 2026-12-31
Amount: Annual profit distribution amount

Review at member meeting

Present pool to members at Annual General Meeting (optional governance)
Show total amount and allocation method

Distribute

Either during meeting or shortly after
Distribution date can be set to meeting date

Communicate to members

Notify members of dividend distribution

Handling Insufficient Retained Earnings

If retained earnings balance is less than pool amount:

Check retained earnings

Navigate to General Ledger → RETAINED_EARNINGS account
View current balance

Identify shortfall

Example: Pool = 5M, Retained Earnings = 3M → 2M shortfall

Choose resolution

Option 1: Delete pool and recreate with lower amount (3M)
Option 2: Release funds from reserves to retained earnings first
Option 3: Wait for more profit to accumulate
Option 4: Use skipNegativeBalanceCheck parameter (not recommended)

skipNegativeBalanceCheck: This parameter allows distribution even if retained earnings would go negative. Only use in exceptional circumstances with full understanding of accounting implications. Creates negative retained earnings balance.

Validation and Constraints

Accounting Period Constraints

Rules enforced at distribution:

✅ At least one accounting period must be closed
✅ pool.periodEnd ≤ last closed accounting period end
✅ distributionDate > last closed accounting period end

Example:

Pool period: Jan 1 - Mar 31, 2026
Last closed period: Mar 31, 2026

Validation:
  - Mar 31 ≤ Mar 31 → ✅ Pass (period end in closed period)
  - Distribution date must be > Mar 31 → Apr 1 or later

If distribution date = Mar 31 or earlier → ❌ Fails validation
If distribution date = Apr 1 or later → ✅ Pass

Balance Constraints

Retained earnings check:

By default, retained earnings must be ≥ pool amount
If insufficient, distribution fails with error
Can override with skipNegativeBalanceCheck: true (use with caution)

Member Eligibility Constraints

Rules:

✅ At least one active member (isActive = true) must exist
✅ Only active members included in allocations
✅ Inactive members automatically excluded

If no active members:

Error: "No active organizationUsers eligible for dividend distribution"

Allocation Constraints

Rules:

✅ Sum of member allocations must exactly equal pool amount
✅ Zero-amount allocations are filtered out
✅ At least one non-zero allocation must exist

Best Practices

Dividend distribution best practices:Before Distributing:

Verify accounting period for pool period is closed
Review all calculated member allocations carefully
Check retained earnings balance is sufficient
Spot-check a few member calculations manually
Document any governance approvals obtained (optional, not enforced by system)

Timing:

Distribute within 1-2 weeks after pool creation
Don’t leave pools in draft status for extended periods
Consider distributing all quarterly pools on same day each quarter

Communication:

Notify members after distribution
Explain distribution method used (equal vs. by_contribution)
Provide information on how to view dividend in their account
Inform members they can withdraw or leave funds to compound

Financial Planning:

Ensure sufficient retained earnings before creating pool
Don’t distribute 100% of profit (keep buffer for operations)
Allocate to reserves before creating dividend pools
Consider upcoming expenses before large distributions

Governance (Optional):

While system has no approval workflow, establish internal governance
Document dividend policy in bylaws
Get appropriate approvals per your organization’s rules
Keep records of approval decisions (meeting minutes, votes)

Error Prevention:

Double-check pool amount before distributing
Verify correct period dates
Review distribution method setting before creating pools
Test with small pool first if new to dividend feature

Troubleshooting

”No accounting period has been closed yet”

Cause: Cannot distribute dividends until at least one accounting period is closed Solution:

Navigate to Accounting Periods

Settings → Accounting Periods

Close the period

Close the accounting period that contains pool.periodEnd

Retry distribution

Return to dividend pool and distribute again

Learn about accounting periods →

“Period end must be on or before last closed period”

Cause: Pool period end is after the last closed accounting period end Example:

Pool period end: Jun 30, 2026
Last closed period end: Mar 31, 2026
Result: ❌ Jun 30 > Mar 31 (fails validation)

Solution:

Close required accounting period

Close the accounting period containing Jun 30, 2026

Or delete and recreate pool

Delete pool and create new pool with earlier period end

Retry distribution

After closing period, distribute pool

”Distribution date must be after last closed period end”

Cause: Custom distribution date is on or before the last closed accounting period end Example:

Last closed period end: Mar 31, 2026
Distribution date: Mar 31, 2026
Result: ❌ Not after closed period

Solution:

Change distribution date to Apr 1, 2026 or later
Or leave blank to use default (pool.periodEnd + 1 day)

“Insufficient retained earnings”

Cause: Retained earnings balance is less than pool amount Possible reasons:

Another dividend distributed after pool creation
Large expenses recorded reducing retained earnings
Funds allocated to reserves
Manual journal entries adjusting retained earnings

Solution:

Check current balance

General Ledger → RETAINED_EARNINGS account → View balance

Determine shortfall

Calculate difference between pool amount and retained earnings

Choose resolution

Option 1: Delete pool, recreate with lower amount
Option 2: Release funds from reserves to retained earnings
Option 3: Wait for more profit to accumulate
Option 4: Record income or adjust previous entries

”No active organizationUsers eligible for dividend distribution”

Cause: No members have isActive = true Solution:

Navigate to Organization Users

View list of all members

Check active status

Verify at least one member has Active status

Activate members if needed

Edit member profiles to set isActive = true

Retry distribution

Return to pool and distribute again

”Computed allocations are zero for all organizationUsers”

Cause: All calculated member allocations are zero (typically in by_contribution method when no members have savings) Solution:

Verify members have savings balances (for by_contribution method)
Check distribution method setting (may need to use equal instead)
Ensure period dates are correct
Review member participation during period

Cannot find pool after distribution

Cause: Default view may filter to only show draft pools Solution:

Change status filter to “All” or “Distributed”
Search by pool period label
Check Dividend Reporting section for historical pools

Member disputes dividend amount

If a member questions their allocation:

Review distribution method

Check if organization uses equal or by_contribution

Explain calculation

Equal: Total ÷ Number of active members
By contribution: (Member savings ÷ Total savings) × Pool amount
Time-weighted: Adjusted by participation days

Verify member data

Check member’s savings balance during period
Verify member was active (isActive = true) at distribution time

If error confirmed

Distribution cannot be undone
Create corrective adjustment (manual journal entry or new small pool)

Correcting Errors After Distribution

Distribution is permanent: Distributed pools cannot be undone, edited, or deleted. All corrections must be made with new transactions.

Option 1: Manual Journal Entry

For small corrections affecting one or two members:

Navigate to Journal Entries

General Ledger → Create Manual Journal Entry

Create correction entry

Kind: ADJUSTMENT
Title: “Dividend Correction - Q1 2026”
Lines:

DEBIT: Member A SAVINGS (reduce overpayment)
CREDIT: Member B SAVINGS (correct underpayment)

Document reason

Add clear description explaining the error and correction

Learn about manual journal entries →

Option 2: Corrective Pool

For larger corrections or errors affecting many members:

Create new dividend pool

Period Label: “Dividend Correction - Q1 2026”
Period: Same as original pool
Amount: Net correction amount

Distribute correction pool

This will create credits to underpaid members
For overpaid members, create separate debit journal entries

Document thoroughly

Explain error and correction in pool description and notes

Option 3: Adjust Next Distribution

For minor discrepancies:

Note correction needed for next period
Adjust next dividend pool to include +/- correction amounts
Document in next pool description

Permissions Required

Action	Permission	Scope
View pools	`dividends:read`	ANY
Distribute pool	`dividends:write`	ANY
View journal entries	`general-ledger:read`	ANY

Typical roles: Administrators and Accountants have dividends:write. Regular members typically have dividends:read (view only) or no access.

Technical Details

API Endpoint

POST /dividends/pools/:poolId/distribute

Headers:
  x-organization-id: <organization_id>
  x-idempotency-key: <unique_key>

Body:
{
  "distributionDate": "2026-04-01",  // Optional, defaults to periodEnd + 1 day
  "skipNegativeBalanceCheck": false  // Optional, default false
}

Response:
{
  "message": "Dividend pool marked as distributed",
  "amount": 5000000
}

Journal Entry Structure

Single journal entry created:

{
  kind: 'DIVIDEND_DISTRIBUTION',
  title: 'Dividend Distribution',
  description: pool.periodLabel,
  transactionDate: distributionDate || (pool.periodEnd + 1 day),
  lines: [
    {
      role: 'RETAINED_EARNINGS',
      side: 'DEBIT',
      amount: poolAmount
    },
    {
      role: 'SAVINGS',
      organizationUserId: 'alice-id',
      side: 'CREDIT',
      amount: aliceAllocation
    },
    {
      role: 'SAVINGS',
      organizationUserId: 'bob-id',
      side: 'CREDIT',
      amount: bobAllocation
    },
    // ... one credit line per member with non-zero allocation
  ]
}

Status Change

Before distribution:

{
  id: poolId,
  journalEntryId: null,  // draft status
  status: 'draft'
}

After distribution:

{
  id: poolId,
  journalEntryId: 'journal-entry-uuid',  // distributed status
  status: 'distributed'
}

Idempotency

The x-idempotency-key header prevents duplicate distributions:

If same key used twice, second request returns cached result
No duplicate journal entries created
Safe to retry failed requests with same key

Dividends Overview

Understand dividend pools and distribution methods

Creating Dividend Pools

Set up new dividend pools

Dividend Reporting

View distribution history and member allocations

Accounting Periods

Understand period closure requirements

Manual Journal Entries

Create corrections after distribution

Retained Earnings

Understand retained earnings accounting

​Overview

​Before You Begin

​Step-by-Step Instructions

​Step 1: Navigate to Pool

​Step 2: Review Calculated Allocations

​Step 3: Verify Prerequisites

​Step 4: Distribute the Pool

​Step 5: Verify Distribution

​What Happens During Distribution

​Distribution Methods

​Equal Distribution

​By Contribution Distribution

​Distribution Date

​Eligibility

​Common Scenarios

​Quarterly Dividend Distribution

​Annual Dividend Distribution

​Handling Insufficient Retained Earnings

​Validation and Constraints

​Accounting Period Constraints

​Balance Constraints

​Member Eligibility Constraints

​Allocation Constraints

​Best Practices

​Troubleshooting

​”No accounting period has been closed yet”

​“Period end must be on or before last closed period”

​”Distribution date must be after last closed period end”

​“Insufficient retained earnings”

​”No active organizationUsers eligible for dividend distribution”

​”Computed allocations are zero for all organizationUsers”

​Cannot find pool after distribution

​Member disputes dividend amount

​Correcting Errors After Distribution

​Option 1: Manual Journal Entry

​Option 2: Corrective Pool

​Option 3: Adjust Next Distribution

​Permissions Required

​Technical Details

​API Endpoint

​Journal Entry Structure

​Status Change

​Idempotency

​Related Topics

Dividends Overview

Creating Dividend Pools

Dividend Reporting

Accounting Periods

Manual Journal Entries

Retained Earnings

Overview

Before You Begin

Step-by-Step Instructions

Step 1: Navigate to Pool

Step 2: Review Calculated Allocations

Step 3: Verify Prerequisites

Step 4: Distribute the Pool

Step 5: Verify Distribution

What Happens During Distribution

Distribution Methods

Equal Distribution

By Contribution Distribution

Distribution Date

Eligibility

Common Scenarios

Quarterly Dividend Distribution

Annual Dividend Distribution

Handling Insufficient Retained Earnings

Validation and Constraints

Accounting Period Constraints

Balance Constraints

Member Eligibility Constraints

Allocation Constraints

Best Practices

Troubleshooting

”No accounting period has been closed yet”

“Period end must be on or before last closed period”

”Distribution date must be after last closed period end”

“Insufficient retained earnings”

”No active organizationUsers eligible for dividend distribution”

”Computed allocations are zero for all organizationUsers”

Cannot find pool after distribution

Member disputes dividend amount

Correcting Errors After Distribution

Option 1: Manual Journal Entry

Option 2: Corrective Pool

Option 3: Adjust Next Distribution

Permissions Required

Technical Details

API Endpoint

Journal Entry Structure

Status Change

Idempotency

Related Topics