Skip to main content

Portfolio Security Events

Portfolio Security Events gather all security events that affected the positions of a portfolio over a period. Instead of looking at one security at a time, you see, in a single place, the income payments, maturities and quantity changes that impacted the portfolio.

These events are essential to understanding returns. An amortization or a dividend returns cash to the investor without a sale taking place; if this flow were not taken into account, the P&L and TWR calculations would be distorted.

Event types​

GorilaCORE classifies each event into a type (eventType). The main families of types are:

  • Cash events (CASH_ prefix): financial flows paid to the security holder, such as dividends (CASH_DIVIDEND), interest on equity (CASH_JSCP), interest (CASH_INTEREST) and amortizations (CASH_AMORTIZATION). They can occur several times throughout the security's life.
  • Custody events (ASSET_ prefix): change the quantity or the identity of the security held, such as splits (ASSET_SPLIT), reverse splits (ASSET_INPLIT), stock bonuses (ASSET_BONUS), spin-offs (ASSET_SPINOFF), mergers or acquisitions (ASSET_MERGER_AND_ACQUISITION) and name changes (ASSET_NAME_CHANGE).
  • Expiration (EXPIRATION): marks the end of the security, common in credit securities and structured products. It occurs only once per security.

There are also types specific to some securities, such as forward expiration (FORWARD_EXPIRATION), subscription receipt conversion (RECEIPT_EXCHANGE) and savings account anniversary (SAVINGS_ANNIVERSARY). The full list of types, with the effect of each one on the position, on returns and on cash, is available at List Security Event Types.

Event dates​

Each event carries two dates. The event date (eventDate), or ex-date, defines who is entitled to the event: the position on that date is what counts. It is also on this date that the impact on the portfolio occurs, both in the return calculation (and in the other portfolio metrics) and in any custody changes, depending on the event (such as reverse splits and splits). The payment date (paymentDate) indicates when the amount is actually credited, and it may occur a few days later.

Event values​

For cash events, the unit value (unitValue) is applied to the quantity held on the event date (sourceQuantity) to arrive at the total amount received (receivedValue). For events that deliver another security, such as stock bonuses and spin-offs, the response indicates the security received (receivedSecurity), the quantity received (receivedQuantity) and the factor applied to the position (eventFactor).

Events on custom securities​

For custom securities, events do not come from a market source: you record them yourself, via Create Security Event. On creation, the event date is provided in the referenceDate field. Once registered, they appear in the portfolio's events like any other.

When recording a cash event, also adjust the security's price on the same date. If a security is worth BRL 1,000.00 and pays an amortization of BRL 600.00, the price should drop to around BRL 400.00; otherwise, the amortization is read as a capital gain.

Where to access​

To list a portfolio's events over a period, with an optional filter by security, see List Security Events. For the events of all portfolios in an economic group, see List Economic Group Security Events.

To measure how much each security paid out in income relative to its price over the period, see the Dividend Yield.