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

# Shares Report

> View member ownership distribution based on savings balances

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

<Note>
  **Permission required**: `reports:read`

  This report is generated from member SAVINGS ledger accounts and shows ownership distribution at a specific point in time.
</Note>

***

## API Endpoint

**Get shares report:**

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

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

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

***

## What is a Share?

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:

1. **Finds all member SAVINGS accounts**
   * Query: `SELECT * FROM ledger_accounts WHERE role = 'SAVINGS'`
   * Each member has one SAVINGS account (scope: `organizationUser:{id}`)

2. **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`

3. **Filters positive balances**
   * Excludes accounts with zero or negative balances
   * Only active members with savings are shown

4. **Calculates percentages**
   * Sum all balances to get `totalShares`
   * For each member: `percentage = (amount / totalShares) × 100`
   * Rounded to 2 decimal places

5. **Sorts by amount**
   * Rows ordered by `amount` descending
   * Largest shareholders appear first

***

## Use Cases

### Dividend Distribution Planning

**Preview dividend allocation before distribution:**

```http theme={null}
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](/tontines/dividends/overview)

***

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

***

## Understanding Share Changes

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

```http theme={null}
# 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:**

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

**Journal entry lines:**

```sql theme={null}
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):**

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

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

***

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

```bash theme={null}
# 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)

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Dividends" icon="hand-coins" href="/tontines/dividends/overview">
    Distribute profits by ownership percentage
  </Card>

  <Card title="Deposits & Savings" icon="money-bill-wave" href="/tontines/deposits-savings/overview">
    Track member savings contributions
  </Card>

  <Card title="Balance Sheet" icon="scale-balanced" href="/tontines/reports/balance-sheet">
    Total shares = Member Savings liability
  </Card>

  <Card title="Member Statements" icon="file-invoice" href="/tontines/reports/member-statements">
    Individual account activity and balances
  </Card>
</CardGroup>