> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributing Dividends

> Calculate member allocations and credit member savings accounts from dividend pools

## 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**.

<Note>
  **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.
</Note>

## Before You Begin

<Note>
  **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
</Note>

<Warning>
  **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.
</Warning>

## Step-by-Step Instructions

### Step 1: Navigate to Pool

<Steps>
  <Step title="Open Dividends section">
    Click **Dividends** in the left sidebar
  </Step>

  <Step title="Find draft pool">
    Locate the pool with status "Draft"
  </Step>

  <Step title="Click on pool">
    Opens pool details page showing calculated allocations
  </Step>
</Steps>

***

### 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

<Note>
  **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.
</Note>

***

### 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

<Steps>
  <Step title="Click Distribute">
    Opens distribution dialog
  </Step>

  <Step title="Set distribution date (optional)">
    **Default**: pool.periodEnd + 1 day<br />
    **Custom**: Choose specific date (must be after last closed period end)
  </Step>

  <Step title="Review warning">
    Dialog warns that distribution is permanent and irreversible
  </Step>

  <Step title="Confirm distribution">
    Click Confirm to proceed
  </Step>
</Steps>

***

### Step 5: Verify Distribution

After distribution completes:

<Steps>
  <Step title="Check pool status">
    Status should now be "Distributed" (journalEntryId populated)
  </Step>

  <Step title="Review journal entry">
    Navigate to General Ledger → Journal Entries<br />
    Find DIVIDEND\_DISTRIBUTION entry<br />
    Verify one debit to RETAINED\_EARNINGS and multiple credits to member SAVINGS
  </Step>

  <Step title="Spot-check member balances">
    Navigate to a few member profiles<br />
    Verify SAVINGS account balance increased by dividend amount
  </Step>

  <Step title="Check retained earnings">
    Navigate to General Ledger → RETAINED\_EARNINGS account<br />
    Verify balance decreased by pool amount
  </Step>
</Steps>

***

## What Happens During Distribution

When you distribute a dividend pool, Agatabo automatically:

1. **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

2. **Retrieves organization settings**
   * Loads distribution method (equal or by\_contribution)
   * Loads time-weighting setting (enabled or disabled)

3. **Identifies eligible members**
   * Queries all organization users with `isActive = true`
   * Excludes inactive members from allocations
   * Requires at least one active member

4. **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

5. **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

6. **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)

7. **Logs audit trail**
   * Records who distributed the pool (actorOrganizationUserId)
   * Timestamp of distribution
   * All journal entry details

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

***

## 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:

<Steps>
  <Step title="Close quarter accounting period">
    Ensure Q1 2026 (Jan-Mar) accounting period is closed
  </Step>

  <Step title="Create draft pool">
    **Period**: 2026-01-01 to 2026-03-31<br />
    **Amount**: Based on profit and dividend policy<br />
    Pool starts in draft status
  </Step>

  <Step title="Review allocations">
    Open pool details and verify calculated member allocations
  </Step>

  <Step title="Distribute">
    Click Distribute<br />
    Default distribution date: 2026-04-01<br />
    Confirm permanent action
  </Step>

  <Step title="Verify">
    Check member SAVINGS accounts increased<br />
    Check RETAINED\_EARNINGS decreased
  </Step>
</Steps>

***

### Annual Dividend Distribution

Year-end distribution:

<Steps>
  <Step title="Close full year">
    Ensure all 2026 accounting periods closed
  </Step>

  <Step title="Create draft pool">
    **Period**: 2026-01-01 to 2026-12-31<br />
    **Amount**: Annual profit distribution amount
  </Step>

  <Step title="Review at member meeting">
    Present pool to members at Annual General Meeting (optional governance)<br />
    Show total amount and allocation method
  </Step>

  <Step title="Distribute">
    Either during meeting or shortly after<br />
    Distribution date can be set to meeting date
  </Step>

  <Step title="Communicate to members">
    Notify members of dividend distribution
  </Step>
</Steps>

***

### Handling Insufficient Retained Earnings

If retained earnings balance is less than pool amount:

<Steps>
  <Step title="Check retained earnings">
    Navigate to General Ledger → RETAINED\_EARNINGS account<br />
    View current balance
  </Step>

  <Step title="Identify shortfall">
    Example: Pool = 5M, Retained Earnings = 3M → 2M shortfall
  </Step>

  <Step title="Choose resolution">
    **Option 1**: Delete pool and recreate with lower amount (3M)<br />
    **Option 2**: Release funds from reserves to retained earnings first<br />
    **Option 3**: Wait for more profit to accumulate<br />
    **Option 4**: Use skipNegativeBalanceCheck parameter (not recommended)
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

***

## 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

<Note>
  **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
</Note>

***

## Troubleshooting

### "No accounting period has been closed yet"

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

**Solution:**

<Steps>
  <Step title="Navigate to Accounting Periods">
    Settings → Accounting Periods
  </Step>

  <Step title="Close the period">
    Close the accounting period that contains pool.periodEnd
  </Step>

  <Step title="Retry distribution">
    Return to dividend pool and distribute again
  </Step>
</Steps>

[Learn about accounting periods →](/tontines/concepts/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:**

<Steps>
  <Step title="Close required accounting period">
    Close the accounting period containing Jun 30, 2026
  </Step>

  <Step title="Or delete and recreate pool">
    Delete pool and create new pool with earlier period end
  </Step>

  <Step title="Retry distribution">
    After closing period, distribute pool
  </Step>
</Steps>

***

### "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:**

<Steps>
  <Step title="Check current balance">
    General Ledger → RETAINED\_EARNINGS account → View balance
  </Step>

  <Step title="Determine shortfall">
    Calculate difference between pool amount and retained earnings
  </Step>

  <Step title="Choose resolution">
    **Option 1**: Delete pool, recreate with lower amount<br />
    **Option 2**: Release funds from reserves to retained earnings<br />
    **Option 3**: Wait for more profit to accumulate<br />
    **Option 4**: Record income or adjust previous entries
  </Step>
</Steps>

***

### "No active organizationUsers eligible for dividend distribution"

**Cause**: No members have `isActive = true`

**Solution:**

<Steps>
  <Step title="Navigate to Organization Users">
    View list of all members
  </Step>

  <Step title="Check active status">
    Verify at least one member has Active status
  </Step>

  <Step title="Activate members if needed">
    Edit member profiles to set isActive = true
  </Step>

  <Step title="Retry distribution">
    Return to pool and distribute again
  </Step>
</Steps>

***

### "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:

<Steps>
  <Step title="Review distribution method">
    Check if organization uses equal or by\_contribution
  </Step>

  <Step title="Explain calculation">
    **Equal**: Total ÷ Number of active members<br />
    **By contribution**: (Member savings ÷ Total savings) × Pool amount<br />
    **Time-weighted**: Adjusted by participation days
  </Step>

  <Step title="Verify member data">
    Check member's savings balance during period<br />
    Verify member was active (isActive = true) at distribution time
  </Step>

  <Step title="If error confirmed">
    Distribution cannot be undone<br />
    Create corrective adjustment (manual journal entry or new small pool)
  </Step>
</Steps>

***

## Correcting Errors After Distribution

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

### Option 1: Manual Journal Entry

For small corrections affecting one or two members:

<Steps>
  <Step title="Navigate to Journal Entries">
    General Ledger → Create Manual Journal Entry
  </Step>

  <Step title="Create correction entry">
    **Kind**: ADJUSTMENT<br />
    **Title**: "Dividend Correction - Q1 2026"<br />
    **Lines**:<br />

    * DEBIT: Member A SAVINGS (reduce overpayment)<br />
    * CREDIT: Member B SAVINGS (correct underpayment)
  </Step>

  <Step title="Document reason">
    Add clear description explaining the error and correction
  </Step>
</Steps>

[Learn about manual journal entries →](/tontines/general-ledger/manual-journal-entries)

### Option 2: Corrective Pool

For larger corrections or errors affecting many members:

<Steps>
  <Step title="Create new dividend pool">
    **Period Label**: "Dividend Correction - Q1 2026"<br />
    **Period**: Same as original pool<br />
    **Amount**: Net correction amount
  </Step>

  <Step title="Distribute correction pool">
    This will create credits to underpaid members<br />
    For overpaid members, create separate debit journal entries
  </Step>

  <Step title="Document thoroughly">
    Explain error and correction in pool description and notes
  </Step>
</Steps>

### 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   |

<Note>
  **Typical roles**: Administrators and Accountants have `dividends:write`. Regular members typically have `dividends:read` (view only) or no access.
</Note>

***

## 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:**

```typescript theme={null}
{
  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:

```typescript theme={null}
{
  id: poolId,
  journalEntryId: null,  // draft status
  status: 'draft'
}
```

After distribution:

```typescript theme={null}
{
  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

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Dividends Overview" icon="info" href="/tontines/dividends/overview">
    Understand dividend pools and distribution methods
  </Card>

  <Card title="Creating Dividend Pools" icon="plus" href="/tontines/dividends/creating-dividend-pools">
    Set up new dividend pools
  </Card>

  <Card title="Dividend Reporting" icon="chart-bar" href="/tontines/dividends/dividend-reporting">
    View distribution history and member allocations
  </Card>

  <Card title="Accounting Periods" icon="calendar" href="/tontines/concepts/accounting-periods">
    Understand period closure requirements
  </Card>

  <Card title="Manual Journal Entries" icon="pen-to-square" href="/tontines/general-ledger/manual-journal-entries">
    Create corrections after distribution
  </Card>

  <Card title="Retained Earnings" icon="piggy-bank" href="/tontines/concepts/retained-earnings">
    Understand retained earnings accounting
  </Card>
</CardGroup>