Guide

Record dividends and return of capital

Record a cash dividend as income, a reinvested dividend as new shares, and a return of capital as a reduction in cost.

A company that shares its profit pays a dividend. You can take it as cash, or have it reinvested in more shares. A return of capital looks the same on the statement but is not income: it hands part of your original investment back, so it lowers the cost you paid for the shares. All three are ordinary transactions.

You need the accounts of Buy and sell shares and an income account for dividends.

Steps

  1. Cash dividend. The dividend is income, so credit an income account, and the cash lands in your brokerage cash account: cash +, Dividends -.
  2. Reinvested dividend. The dividend is income and you spend it at once on shares: the share account + with its amount in shares and its value in dollars, and Dividends -. No cash moves. Set currency, since the first split may be in shares.
  3. Return of capital. Cash arrives and the cost of the shares falls: cash +, and the share account - with a value and an amount of 0. The shares are the same; they cost less.
  4. Foreign withholding tax or fees are further expense splits in the same transaction.
  5. Check with account.balance.

Example

Example: with a new, empty book open as book.gnucash, at 2024-07-31T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Cash","type":"BANK","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"AAPL","type":"STOCK","commodity":"NASDAQ::AAPL"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Dividends","type":"INCOME","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":5,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-06-01","description":"Opening","currency":"USD","splits":[{"account":"AAPL","value":"1500.00","amount":"10"},{"account":"Opening Balances","value":"-1500.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":7,"method":"transaction.post","params":{"datePosted":"2024-07-10","description":"Cash dividend","splits":[{"account":"Cash","value":"24.00"},{"account":"Dividends","value":"-24.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-07-15","description":"Reinvested dividend","currency":"USD","splits":[{"account":"AAPL","value":"24.00","amount":"0.15"},{"account":"Dividends","value":"-24.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":9,"method":"transaction.post","params":{"datePosted":"2024-07-20","description":"Return of capital","currency":"USD","splits":[{"account":"Cash","value":"50.00"},{"account":"AAPL","value":"-50.00","amount":"0"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":10,"method":"account.balance","params":{"account":"AAPL"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "101500",
        "denom": "10000"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":11,"method":"account.balance","params":{"account":"Dividends"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "balances": {
      "balance": {
        "num": "-4800",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
commodity.create {"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}
account.create {"name":"Cash","type":"BANK","commodity":"USD"}
account.create {"name":"AAPL","type":"STOCK","commodity":"NASDAQ::AAPL"}
account.create {"name":"Dividends","type":"INCOME","commodity":"USD"}
account.create {"name":"Opening Balances","type":"EQUITY","commodity":"USD"}
transaction.post {"datePosted":"2024-06-01","description":"Opening","currency":"USD","splits":[{"account":"AAPL","value":"1500.00","amount":"10"},{"account":"Opening Balances","value":"-1500.00"}]}
transaction.post {"datePosted":"2024-07-10","description":"Cash dividend","splits":[{"account":"Cash","value":"24.00"},{"account":"Dividends","value":"-24.00"}]}
transaction.post {"datePosted":"2024-07-15","description":"Reinvested dividend","currency":"USD","splits":[{"account":"AAPL","value":"24.00","amount":"0.15"},{"account":"Dividends","value":"-24.00"}]}
transaction.post {"datePosted":"2024-07-20","description":"Return of capital","currency":"USD","splits":[{"account":"Cash","value":"50.00"},{"account":"AAPL","value":"-50.00","amount":"0"}]}
account.balance {"account":"AAPL"}
account.balance {"account":"Dividends"}
EOF

It prints:

[
  "…",
  "…",
  "…",
  "…",
  "…",
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "101500",
        "denom": "10000"
      },
      "…": "…"
    },
    "…": "…"
  },
  {
    "balances": {
      "balance": {
        "num": "-4800",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"commodity.create","arguments":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Cash","type":"BANK","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"AAPL","type":"STOCK","commodity":"NASDAQ::AAPL"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Dividends","type":"INCOME","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-06-01","description":"Opening","currency":"USD","splits":[{"account":"AAPL","value":"1500.00","amount":"10"},{"account":"Opening Balances","value":"-1500.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-10","description":"Cash dividend","splits":[{"account":"Cash","value":"24.00"},{"account":"Dividends","value":"-24.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-15","description":"Reinvested dividend","currency":"USD","splits":[{"account":"AAPL","value":"24.00","amount":"0.15"},{"account":"Dividends","value":"-24.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-20","description":"Return of capital","currency":"USD","splits":[{"account":"Cash","value":"50.00"},{"account":"AAPL","value":"-50.00","amount":"0"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"AAPL"}}

Result:

{
  "structuredContent": {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "101500",
        "denom": "10000"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Dividends"}}

Result:

{
  "structuredContent": {
    "balances": {
      "balance": {
        "num": "-4800",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}