Shares Report - Agatabo

Overview

The Shares Report displays each member’s savings balance and their percentage ownership of total member savings, providing a clear view of equity distribution in the organization.

Permission required: reports:readThis report is generated from member SAVINGS ledger accounts and shows ownership distribution at a specific point in time.

API Endpoint

Get shares report:

GET /reports/shares-report?asOfDate={date}
Headers:
  x-organization-id: {organizationId}

Query parameters:

Parameter	Type	Required	Description
`asOfDate`	string (ISO date)	No	Snapshot date for share calculation. Defaults to current date.

Example request:

curl -X GET "https://api.agatabo.com/reports/shares-report?asOfDate=2026-06-30" \
  -H "x-organization-id: org-abc123" \
  -H "Authorization: Bearer {token}"

Response Structure

{
  "asOfDate": "2026-06-30T00:00:00.000Z",
  "totalShares": 10000000.00,
  "rows": [
    {
      "organizationUserId": "orguser-123",
      "name": "John Doe",
      "accountNumber": "SAV-001",
      "amount": 1200000.00,
      "percentage": 12.00
    },
    {
      "organizationUserId": "orguser-456",
      "name": "Jane Smith",
      "accountNumber": "SAV-002",
      "amount": 1000000.00,
      "percentage": 10.00
    },
    {
      "organizationUserId": "orguser-789",
      "name": "Peter Kalisa",
      "accountNumber": "SAV-003",
      "amount": 800000.00,
      "percentage": 8.00
    }
    // ... more rows
  ]
}

Response fields:

Field	Type	Description
`asOfDate`	string (ISO datetime)	Report snapshot date
`totalShares`	number	Total of all member savings balances
`rows`	array	Individual member share records (sorted by amount descending)
`rows[].organizationUserId`	string	Organization user ID
`rows[].name`	string	Member name
`rows[].accountNumber`	string	Savings account number
`rows[].amount`	number	Member’s savings balance
`rows[].percentage`	number	Ownership percentage (amount ÷ totalShares × 100)

Important notes:

Sorted by amount: Rows are ordered by savings balance, highest to lowest
Positive balances only: Members with zero or negative balances are excluded
Current balances: Calculated from all journal entries posted up to asOfDate
SAVINGS accounts: Data comes from ledger accounts with role SAVINGS and scope organizationUser:{id}

In Agatabo’s tontine model: Share = Member’s total savings balance Share percentage = (Member’s savings ÷ Total all member savings) × 100 Example:

Total member savings: 10,000,000 RWF
Jane's savings:          500,000 RWF
Jane's share:                5.00%

This percentage determines:

Dividend allocation (if distributed by contribution)
Ownership stake in organization equity
Proportional interest in organization assets

How It Works

The shares report:

Finds all member SAVINGS accounts
- Query: SELECT * FROM ledger_accounts WHERE role = 'SAVINGS'
- Each member has one SAVINGS account (scope: organizationUser:{id})
Calculates balance up to asOfDate
- Sum all journal entry lines for each account
- SAVINGS is LIABILITY type: CREDIT increases balance, DEBIT decreases balance
- Formula: balance += (side === 'CREDIT' ? amount : -amount)
- Only includes POSTED journal entries up to and including asOfDate
Filters positive balances
- Excludes accounts with zero or negative balances
- Only active members with savings are shown
Calculates percentages
- Sum all balances to get totalShares
- For each member: percentage = (amount / totalShares) × 100
- Rounded to 2 decimal places
Sorts by amount
- Rows ordered by amount descending
- Largest shareholders appear first

Use Cases

Dividend Distribution Planning

Preview dividend allocation before distribution:

GET /reports/shares-report?asOfDate=2026-06-30

If distributing 500,000 RWF profit by contribution:

John Doe (12.00%): 60,000 RWF
Jane Smith (10.00%): 50,000 RWF
Peter Kalisa (8.00%): 40,000 RWF

See: Dividends by Contribution

Member Equity Tracking

Show members their ownership stake: At Annual General Meeting, present shares report to demonstrate:

Each member’s current savings balance
Ownership percentage of total organization savings
How ownership has changed over the year (compare to prior year report)

Financial Transparency

Answer “How much do I own?” questions: The shares report provides clear, auditable answers:

“You have 500,000 RWF in savings”
“That represents 5.00% ownership”
“If we distributed all savings today, you would receive 5% of the total”

Board Reporting

Present ownership structure at meetings: Use shares report to show:

Ownership concentration: Are savings distributed evenly or concentrated?
Member engagement: How many members actively contribute?
Growth trends: Compare total shares to prior periods

Shares increase when:

Member makes deposits
Interest credited to savings (if applicable)
Dividends added to savings

Shares decrease when:

Member makes withdrawals (if allowed by organization rules)
Fees deducted from savings

Share percentage changes when: Even if your balance stays the same, your percentage can change: Example:

Month 1:
  Jane:   500,000 RWF out of 10,000,000 total = 5.00%

Month 2 (Jane deposits 100,000 RWF):
  Jane:   600,000 RWF
  Other members deposit 2,000,000 RWF
  New total: 12,100,000 RWF
  Jane's new percentage: 4.96% (decreased despite higher balance!)

Why? Because other members’ deposits increased the total pool, diluting Jane’s percentage.

Comparing Periods

Track ownership changes over time:

# Prior month
GET /reports/shares-report?asOfDate=2026-05-31

# Current month
GET /reports/shares-report?asOfDate=2026-06-30

What to compare:

Change in individual member balances
Change in share percentages
Total shares (organization growth)
New members added
Members who withdrew or left (no longer in report)

Analysis example:

Member	May Balance	May %	June Balance	June %	Change
John Doe	1,100,000	11.00%	1,200,000	12.00%	+1.00%
Jane Smith	1,000,000	10.00%	1,000,000	10.00%	0.00%
Peter Kalisa	750,000	7.50%	800,000	8.00%	+0.50%

Insights:

John Doe increased savings and ownership percentage (deposited 100,000 RWF)
Jane Smith’s balance and percentage unchanged (no activity)
Peter Kalisa increased savings and ownership percentage (deposited 50,000 RWF)

Key Metrics

Calculate from shares report data: Average share per member:

Average = totalShares ÷ number of rows

Ownership concentration:

Top 10% concentration = (Sum of top 10% of members) ÷ totalShares × 100

Target: Healthy organizations typically have 20-40% concentration in top 10% of members Member participation:

Active members = number of rows in report
Participation rate = (Active members ÷ Total registered members) × 100

Target: >80% of registered members actively saving

Relationship to Other Reports

Balance Sheet:

Total shares = “Member Savings” liability on Balance Sheet
Shares report breaks down this total by individual member

Example reconciliation:

Balance Sheet (as of June 30, 2026):
  LIABILITIES
    Member Savings: 10,000,000 RWF

Shares Report (as of June 30, 2026):
  Total Shares: 10,000,000 RWF ✓ (must match)

Dividends:

When distributing dividends “by contribution”, shares report shows the basis
Each member receives: (Total dividend × member’s percentage)

Data Source

Shares report is generated from: SAVINGS ledger accounts:

SELECT * FROM ledger_accounts
WHERE organization_id = {orgId}
  AND role_definition.role = 'SAVINGS'
  AND scope_key LIKE 'organizationUser:%'

Journal entry lines:

SELECT * FROM journal_entry_lines
WHERE ledger_account_id IN (savings_account_ids)
  AND journal_entry.status = 'POSTED'
  AND journal_entry.posted_at <= {asOfDate}

Balance calculation (SAVINGS is LIABILITY):

let balance = 0;
for (const line of journalLines) {
  // CREDIT increases liability (deposits)
  // DEBIT decreases liability (withdrawals)
  balance += line.side === 'CREDIT' ? line.amount : -line.amount;
}

Best Practices

Generating shares reports:Timing:

✅ Generate after period close for accurate historical snapshots
✅ Run before dividend distribution to calculate allocations
✅ Review quarterly to track ownership trends
✅ Present at Annual General Meetings for transparency

Accuracy:

✅ Ensure all deposits and withdrawals are posted before generating report
✅ Verify totalShares matches “Member Savings” on Balance Sheet
✅ Spot-check member balances against individual statements
✅ Investigate any unexpected percentage changes

Analysis:

✅ Compare to prior period to identify trends
✅ Calculate average share to understand typical member savings
✅ Monitor ownership concentration for equity distribution
✅ Track member participation rate (active savers ÷ total members)

Communication:

✅ Share report with members at quarterly meetings
✅ Explain how percentages are calculated
✅ Show relationship to dividend distribution
✅ Address questions about share changes openly

Common Questions

Q: Why do shares not match total contributions? A: Shares = current balance, not total contributions. Balance may differ due to:

Withdrawals made (reduces balance)
Interest credited to savings (increases balance)
Dividends added to savings (increases balance)
Fees deducted (reduces balance)

Q: Does share percentage affect voting rights? A: This depends on your organization’s bylaws:

One member, one vote: Share percentage irrelevant for voting
Weighted voting: Votes proportional to ownership percentage

Check your organization’s governance rules. Q: Can percentages not add to exactly 100%? A: Rounding to 2 decimal places may cause slight discrepancies. Backend calculates exact percentages; displayed values are rounded for readability. Total should be very close to 100.00%. Q: Why is a member missing from the report? A: Members with zero or negative savings balances are excluded. Possible reasons:

New member who hasn’t deposited yet
Member withdrew all savings
Data entry error (check member statements)

Q: Can members see other members’ shares? A: Depends on permission configuration:

Users with reports:read permission can view all members’ shares
Typically: Administrators, Accountants, Treasurers, Board Members
Regular members: May only see their own balance (via member statements)

Check with administrator about access policy.

Example: Quarterly Analysis

Scenario: Compare Q1 and Q2 shares to identify trends API calls:

# Q1 (end of March)
curl -X GET "https://api.agatabo.com/reports/shares-report?asOfDate=2026-03-31" \
  -H "x-organization-id: org-abc123"

# Q2 (end of June)
curl -X GET "https://api.agatabo.com/reports/shares-report?asOfDate=2026-06-30" \
  -H "x-organization-id: org-abc123"

Analysis:

Metric	Q1 (Mar 31)	Q2 (Jun 30)	Change
Total Shares	9,500,000	10,000,000	+5.26%
Number of Members	24	25	+1 member
Average Share	395,833	400,000	+1.05%
Largest Share	1,150,000 (12.11%)	1,200,000 (12.00%)	+50,000

Insights:

Organization grew by 500,000 RWF in savings (healthy growth)
One new member joined
Average share per member increased (existing members saving more)
Largest shareholder increased balance but percentage slightly decreased (good - less concentration)

Dividends

Distribute profits by ownership percentage

Deposits & Savings

Track member savings contributions

Balance Sheet

Total shares = Member Savings liability

Member Statements

Individual account activity and balances

​Overview

​API Endpoint

​Response Structure

​What is a Share?

​How It Works

​Use Cases

​Dividend Distribution Planning

​Member Equity Tracking

​Financial Transparency

​Board Reporting

​Understanding Share Changes

​Comparing Periods

​Key Metrics

​Relationship to Other Reports

​Data Source

​Best Practices

​Common Questions

​Example: Quarterly Analysis

​Related Topics

Dividends

Deposits & Savings

Balance Sheet

Member Statements

Overview

API Endpoint

Response Structure

What is a Share?

How It Works

Use Cases

Dividend Distribution Planning

Member Equity Tracking

Financial Transparency

Board Reporting

Understanding Share Changes

Comparing Periods

Key Metrics

Relationship to Other Reports

Data Source

Best Practices

Common Questions

Example: Quarterly Analysis

Related Topics