> ## 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. # Dividend Reporting > View dividend pool history, member allocations, and distribution analytics ## Overview Dividend reporting provides visibility into profit distributions over time, allowing you to track dividend pools, view member allocations, analyze distribution patterns, and provide transparency to members about how retained earnings are shared. **What you can view**: Pool lists with filtering and sorting, individual pool details with member allocations, member dividend history, and organization-level analytics. ## Accessing Dividend Information ### Dividend Pools List View all dividend pools (draft and distributed) with filtering and sorting options. Click **Dividends** in the left sidebar See all dividend pools for your organization Filter by status, date range, or sort by different criteria **Information displayed:** * **Period label**: Descriptive name (e.g., "Q1 2026 Dividend") * **Period dates**: Start and end dates of dividend period * **Amount**: Total pool amount to distribute * **Status**: Draft (journalEntryId = null) or Distributed (journalEntryId populated) * **Distribution date**: Transaction date of journal entry (if distributed) * **Eligible members count**: Number of active members who received/will receive dividends *** ### Individual Pool Details View detailed information about a specific dividend pool, including calculated member allocations. From pools list, click on any pool See pool metadata and distribution settings See calculated dividend amount for each member Sort by amount, name, or email; search for specific members **Pool details shown:** * Period label, start date, end date * Total pool amount * Status (draft or distributed) * Distribution method (equal or by\_contribution) * Time-weighting setting (enabled or disabled) * Distribution basis (equal split, participation days, contribution amount, time-weighted contribution) * Journal entry details (if distributed) **Member allocations shown:** * Member name and email * Calculated dividend amount * Distribution basis value (participation days, contribution amount, etc.) * Percentage of total pool * SAVINGS account scope key (if distributed) *** ### Member Dividend History View all dividends received by a specific member across all pools. Organization Users → Click on member See member's dividend history See all pools where member received dividends **Member history includes:** * Pool period label * Distribution date * Dividend amount received * Pool total amount * Percentage of pool received * Cumulative total dividends *** ## Filtering and Searching ### Filter by Status **Draft pools** (`journalEntryId = null`): * Pools created but not yet distributed * Member allocations are calculated but not posted * Can still be edited or deleted * No journal entry created yet **Distributed pools** (`journalEntryId ≠ null`): * Pools that have been finalized * Journal entry created, SAVINGS accounts credited * Cannot be edited or deleted (permanent) * Locked for audit trail **Filter syntax:** ``` /dividends/pools?status=draft /dividends/pools?status=distributed /dividends/pools (all pools, no filter) ``` *** ### Filter by Date Range Filter pools by period end date within a specific range. **Examples:** ``` View 2026 pools: /dividends/pools?startDate=2026-01-01&endDate=2026-12-31 View Q1-Q2 2026: /dividends/pools?startDate=2026-01-01&endDate=2026-06-30 View pools after specific date: /dividends/pools?startDate=2026-04-01 ``` **Filtering logic:** * Filters on `periodEnd` field * `startDate`: Include pools where periodEnd ≥ startDate * `endDate`: Include pools where periodEnd ≤ endDate *** ### Sorting Pools Sort dividend pools by different criteria. **Sort options:** * **periodEnd**: Sort by period end date (default: descending) * **periodStart**: Sort by period start date * **createdAt**: Sort by pool creation date * **totalAmount**: Sort by pool amount * **status**: Sort by status (distributed vs. draft) **Sort order:** * **desc**: Descending (most recent/largest first) - default * **asc**: Ascending (oldest/smallest first) **Examples:** ``` Largest pools first: /dividends/pools?sortBy=totalAmount&sortOrder=desc Oldest pools first: /dividends/pools?sortBy=createdAt&sortOrder=asc Most recent period end first (default): /dividends/pools?sortBy=periodEnd&sortOrder=desc ``` *** ### Sorting Member Allocations Within a pool's member allocations, sort by different criteria. **Sort options:** * **amount**: Sort by dividend amount * **organizationUserName**: Sort by member name * **organizationUserEmail**: Sort by member email **Examples:** ``` Largest dividends first: /dividends/pools/:poolId?sortBy=amount&sortOrder=desc Alphabetical by name: /dividends/pools/:poolId?sortBy=organizationUserName&sortOrder=asc ``` *** ### Search Members Search for specific members within a pool's allocations. **Search by:** * Member name (partial match) * Member email (partial match) **Example:** ``` /dividends/pools/:poolId?search=alice (Returns members with "alice" in name or email) ``` *** ### Pagination Both pool lists and member allocations support pagination. **Pool list pagination:** ``` /dividends/pools?page=1&limit=20 ``` **Member allocations pagination:** ``` /dividends/pools/:poolId?page=1&limit=50 ``` **Defaults:** * Pools: No limit (all pools returned) * Member allocations: No limit (all members returned) * Maximum limit: 100 (pools), 100 (member allocations) *** ## Key Dividend Metrics ### Total Dividends Distributed Sum of all distributed pools = total retained earnings distributed to members **Calculation:** ``` Query all pools with status = 'distributed' Sum pool amounts ``` **Example annual summary:** ``` Q1 2026: 3,000,000 RWF (distributed) Q2 2026: 4,000,000 RWF (distributed) Q3 2026: 3,500,000 RWF (distributed) Q4 2026: 5,000,000 RWF (distributed) Draft pools: 2,000,000 RWF (not yet distributed) Total distributed in 2026: 15,500,000 RWF Total planned (including drafts): 17,500,000 RWF ``` *** ### Average Dividend per Member Total distributed ÷ number of unique members who received dividends **Calculation:** * Query all distributed pools * Count unique members who received dividends * Divide total distributed by member count **Example:** ``` Total distributed (2026): 15,500,000 RWF Unique members who received dividends: 50 Average per member: 310,000 RWF ``` **Note**: This is a simple average. Actual member amounts vary based on distribution method (equal vs. by\_contribution) and time-weighting. *** ### Dividend Payout Ratio Dividends ÷ net profit = percentage of profit distributed to members **Calculation:** ``` Net profit (from Income Statement): 25,000,000 RWF Total dividends distributed: 15,000,000 RWF Payout ratio: 15M ÷ 25M = 60% ``` **Interpretation:** * High ratio (70-80%): More profit to members, less retained for growth * Medium ratio (50-60%): Balanced approach * Low ratio (20-40%): More retained for reserves and expansion **Remaining allocation:** * Reserves: Allocated to emergency fund, equipment, etc. * Retained earnings: Kept for future operations and growth *** ### Individual Member Totals For each member, calculate cumulative dividends received. **Query:** ``` GET /dividends/by-organization-user/:organizationUserId ``` **Returns:** * List of all pools where member received dividend * Amount received in each pool * Period label and distribution date * Cumulative total **Example member summary:** ``` Member: Alice Dividends received: Q1 2026: 150,000 RWF Q2 2026: 180,000 RWF Q3 2026: 165,000 RWF Q4 2026: 205,000 RWF Total lifetime dividends: 700,000 RWF ``` *** ## Balance Sheet Integration Dividends move funds from retained earnings to member savings accounts. **Before distribution:** ``` EQUITY Retained Earnings: 20,000,000 RWF (Member SAVINGS shown in LIABILITIES section) ``` **After distributing 5,000,000 RWF dividend:** ``` EQUITY Retained Earnings: 15,000,000 RWF (decreased by 5M) LIABILITIES Member Savings: +5,000,000 RWF (increased by 5M) ``` **Journal entry created:** ``` DEBIT: Retained Earnings -5,000,000 RWF CREDIT: Member SAVINGS +5,000,000 RWF (split among members) ``` **Important**: Dividends credit member SAVINGS accounts (liability), NOT a separate "Member Equity" account. This increases member balances they can withdraw or leave to compound. [Learn about balance sheet →](/tontines/reports/balance-sheet) *** ## Dividend Analytics Access organization-level dividend analytics and trends. **Endpoint:** ``` GET /dividends/analytics?startDate=2026-01-01&endDate=2026-12-31 ``` **Analytics endpoint status**: The analytics endpoint exists but currently returns placeholder data (all zeros). Full analytics implementation is planned for future release. Use pool list queries to calculate metrics manually. **Placeholder response structure:** ```typescript theme={null} { period: 'QUARTERLY', distributionMethod: 'equal', totalPools: 0, draftPoolsCount: 0, distributedPoolsCount: 0, totalDistributedAmount: 0, totalDraftAmount: 0, totalDistributionsPaid: 0, byPeriod: [], dividendsPerPeriodChart: [], draftVsDistributedChart: { draft: { amount: 0, count: 0 }, distributed: { amount: 0, count: 0 } } } ``` **Manual analytics calculation:** * Query all pools with appropriate filters * Sum amounts, count pools, group by period * Use response data to calculate custom analytics *** ## Reporting to Members ### Quarterly Dividend Report After each distribution, communicate with members: **Report template:** ``` QUARTERLY DIVIDEND REPORT Period: Q1 2026 (January 1 - March 31, 2026) FINANCIAL SUMMARY Total Revenue: 18,000,000 RWF Total Expenses: 6,000,000 RWF Net Profit: 12,000,000 RWF DIVIDEND ALLOCATION Pool Amount: 6,000,000 RWF (50% of profit) Eligible Members: 48 active members Distribution Method: By Contribution (Time-Weighted) Distribution Date: April 5, 2026 INDIVIDUAL SHARES Range: 50,000 - 300,000 RWF per member Average: 125,000 RWF per member Your Dividend: [View in your account] PROFIT ALLOCATION Dividends to Members: 6,000,000 RWF (50%) Reserves: 3,000,000 RWF (25%) Retained Earnings: 3,000,000 RWF (25%) HOW TO ACCESS Log in to your account to view your dividend in transaction history. Funds have been added to your SAVINGS balance. ``` *** ### Member Dividend Statement Provide individual members with personalized dividend summary: ``` MEMBER DIVIDEND STATEMENT Member: John Doe Account: ACC-0042 Period: January 1 - December 31, 2026 DIVIDENDS RECEIVED Q1 2026: 150,000 RWF (Distributed April 5) Q2 2026: 180,000 RWF (Distributed July 8) Q3 2026: 165,000 RWF (Distributed October 6) Q4 2026: 205,000 RWF (Distributed January 10, 2027) TOTAL 2026 DIVIDENDS: 700,000 RWF DISTRIBUTION METHOD By Contribution (Time-Weighted) Your contributions are weighted by how long funds were held during each period. SAVINGS SUMMARY Opening Balance (Jan 1, 2026): 7,800,000 RWF Dividends Received: 700,000 RWF New Deposits: 1,200,000 RWF Withdrawals: (500,000) RWF Interest Earned: 450,000 RWF Closing Balance (Dec 31, 2026): 9,650,000 RWF DIVIDEND YIELD: 7.2% of average savings balance Thank you for your continued participation! ``` *** ## Distribution Method Impact ### Equal Distribution All active members receive the same amount (or time-weighted equal shares). **Pool details display:** ``` Distribution Method: Equal Time-Weighting: Disabled Basis: Equal split Basis Unit: count Member allocations: Alice: 200,000 RWF (1 of 50 members = 2%) Bob: 200,000 RWF (1 of 50 members = 2%) Carol: 200,000 RWF (1 of 50 members = 2%) ... (all 50 members get 200,000 RWF each) ``` **With time-weighting enabled:** ``` Distribution Method: Equal Time-Weighting: Enabled Basis: Participation days Basis Unit: days Member allocations: Alice: 300,000 RWF (90 days / 180 total = 50%) Bob: 200,000 RWF (60 days / 180 total = 33.3%) Carol: 100,000 RWF (30 days / 180 total = 16.7%) ``` *** ### By Contribution Distribution Members receive dividends proportional to their savings contributions. **Pool details display:** ``` Distribution Method: By Contribution Time-Weighting: Disabled Basis: Contribution amount Basis Unit: RWF Member allocations: Alice: 2,000,000 RWF savings → 2,000,000 RWF dividend (40% of pool) Bob: 1,500,000 RWF savings → 1,500,000 RWF dividend (30% of pool) Carol: 1,500,000 RWF savings → 1,500,000 RWF dividend (30% of pool) Total savings: 5,000,000 RWF → Total pool: 5,000,000 RWF ``` **With time-weighting enabled:** ``` Distribution Method: By Contribution Time-Weighting: Enabled Basis: Time-weighted contribution Basis Unit: RWF-days Allocations weighted by how long contributions were held during period. Alice (held 2M for 90 days): Higher allocation Bob (deposited 2M on day 89): Lower allocation despite same balance ``` *** ## Common Use Cases ### View All Distributed Pools for 2026 ``` GET /dividends/pools?status=distributed&startDate=2026-01-01&endDate=2026-12-31&sortBy=periodEnd&sortOrder=asc ``` Returns all distributed pools in chronological order for the year. *** ### Find Largest Draft Pools ``` GET /dividends/pools?status=draft&sortBy=totalAmount&sortOrder=desc ``` Returns draft pools sorted by amount (largest first). *** ### View Member's Dividend History ``` GET /dividends/by-organization-user/:organizationUserId?page=1&limit=20 ``` Returns paginated list of dividends received by specific member. *** ### Search for Pool by Label Filter pools list in UI by typing pool label (e.g., "Q1 2026"). *** ### View Pool with Specific Members ``` GET /dividends/pools/:poolId?search=alice ``` Returns pool details with only members matching "alice" in name or email. *** ## Best Practices **Dividend reporting best practices:** **Frequency:** * Review pools list after each distribution * Provide member statements quarterly or annually * Monitor draft pools regularly (don't leave in draft too long) **Transparency:** * Share distribution method with all members * Explain time-weighting if enabled * Publish dividend schedule at start of year * Make pool details accessible to all members (not just board) **Communication:** * Send announcement within 1 week of distribution * Include individual statements for members * Explain any changes to distribution policy * Celebrate milestones (e.g., "Total 50M distributed since inception!") **Analysis:** * Track dividend trends year-over-year * Compare draft vs. distributed pools * Monitor payout ratio (don't distribute 100% of profit) * Identify members who haven't received dividends (inactive members) **Documentation:** * Export pool data for annual reports * Keep records of approval decisions (if governance requires) * Document distribution method changes in meeting minutes * Archive member statements for audit trail **Member Education:** * Explain how to view dividends in their account * Clarify difference between SAVINGS balance and dividends * Show how to check transaction history * Explain withdrawal vs. compound options *** ## Troubleshooting ### Cannot find distributed pool **Possible causes:** * Status filter set to "Draft" only * Date range filter excludes pool's period end date * Searching for wrong pool label **Solution:** Remove status filter, date range, and search terms Most recent pools appear first Verify pool was actually distributed (journalEntryId ≠ null) *** ### Member allocation shows zero **Possible causes:** * Member was inactive (isActive = false) at distribution time * Member had no savings (in by\_contribution method) * Member's calculated allocation rounded to zero **Solution:** * Check member's active status during pool period * Verify member had savings balance (for by\_contribution method) * Review distribution method and time-weighting settings *** ### Pool total doesn't match sum of member allocations **Cause:** Viewing draft pool with members filtered by search **Explanation:** * Search filters member allocations display * Pool total remains unchanged * Sum of visible allocations may not equal pool total **Solution:** * Clear search filter to see all members * Verify sum of all member allocations equals pool total *** ### Member disputes dividend amount **Investigation steps:** Open the pool and find the member's allocation Equal or by\_contribution? Time-weighted? Check member's participation days or contribution amount (Member basis ÷ Total basis) × Pool amount = Member allocation Was member active (isActive = true) during period? **Common explanations:** * Member joined mid-period (time-weighted equal) * Member had lower savings (by\_contribution method) * Member was inactive during distribution *** ### Analytics shows all zeros **Cause:** Analytics endpoint returns placeholder data (not yet implemented) **Solution:** * Use pools list endpoint to manually calculate analytics * Query pools with appropriate filters * Sum amounts and count pools in application code * Await future release with full analytics implementation *** ## Permissions Required | Action | Permission | Scope | | -------------------------------- | ---------------- | --------------------------- | | View all pools | `dividends:read` | ANY | | View pool details | `dividends:read` | ANY | | View member allocations | `dividends:read` | ANY | | View specific member's dividends | `dividends:read` | organizationUserId (scoped) | | View analytics | `dividends:read` | ANY | **Typical roles**: * Administrators and Accountants: `dividends:read` (ANY scope) - can view all pools and all member allocations * Regular members: `dividends:read` (own organizationUserId scope) - can only view their own dividend history *** ## Technical Details ### API Endpoints **List pools:** ``` GET /dividends/pools Query parameters: status?: 'draft' | 'distributed' startDate?: YYYY-MM-DD (ISO date string) endDate?: YYYY-MM-DD (ISO date string) sortBy?: 'periodEnd' | 'periodStart' | 'createdAt' | 'totalAmount' | 'status' sortOrder?: 'asc' | 'desc' page?: number (min 1) limit?: number (min 1, max 100) Response: [ { id: string, organizationId: string, periodLabel: string, periodStart: Date, periodEnd: Date, totalAmount: number, status: 'draft' | 'distributed', createdAt: Date, distributedAt: Date | null, eligibleMembersCount: number, distributionMethod: 'equal' | 'by_contribution', timeWeighted: boolean }, ... ] ``` **Get pool details:** ``` GET /dividends/pools/:poolId Query parameters: page?: number (min 1) limit?: number (min 1, max 100) sortBy?: 'amount' | 'organizationUserName' | 'organizationUserEmail' sortOrder?: 'asc' | 'desc' search?: string (search member name or email) Response: { pool: { id: string, periodLabel: string, periodStart: Date, periodEnd: Date, totalAmount: number, status: 'draft' | 'distributed', distributionMethod: 'equal' | 'by_contribution', timeWeighted: boolean, basisLabel: string, // e.g., "Equal split", "Participation days", "Contribution amount" basisUnit: string, // e.g., "count", "days", "RWF" journalEntryId: string | null }, allocations: [ { organizationUserId: string, memberName: string, memberEmail: string, amount: number, basisValue: number, percentageOfPool: number, scopeKey: string // e.g., "organizationUser:abc123" }, ... ], pagination: { page: number, limit: number, total: number } } ``` **Get member dividend history:** ``` GET /dividends/by-organization-user/:organizationUserId Query parameters: page?: number (min 1) limit?: number (min 1, max 200) Response: { dividends: [ { poolId: string, periodLabel: string, periodStart: Date, periodEnd: Date, amount: number, distributedAt: Date, poolTotalAmount: number, percentageOfPool: number }, ... ], summary: { totalDividends: number, poolsCount: number }, pagination: { page: number, limit: number, total: number } } ``` **Get analytics (placeholder):** ``` GET /dividends/analytics Query parameters: startDate?: YYYY-MM-DD endDate?: YYYY-MM-DD sortBy?: 'periodEnd' | 'periodStart' | 'totalAmount' | 'status' | 'distributedAt' | 'eligibleOrganizationUserCount' sortOrder?: 'asc' | 'desc' Response (placeholder - all zeros): { period: 'QUARTERLY' | 'YEARLY', distributionMethod: 'equal' | 'by_contribution', totalPools: 0, draftPoolsCount: 0, distributedPoolsCount: 0, totalDistributedAmount: 0, totalDraftAmount: 0, totalDistributionsPaid: 0, byPeriod: [], dividendsPerPeriodChart: [], draftVsDistributedChart: { draft: { amount: 0, count: 0 }, distributed: { amount: 0, count: 0 } } } ``` *** ## Related Topics Understand dividend pools and distribution methods Set up new dividend pools Calculate allocations and make payments View how dividends affect equity and liabilities Calculate net profit for dividend allocation Understand retained earnings accounting