Modelling a dividend option (DVOP)

You can model a dividend option as a corporate action of type DividendOptionEvent in LUSID. See all supported corporate actions.

Note the following:

DividendOptionEvent is valid for instruments of type Equity and SimpleInstrument.
A dividend option gives the holder a choice between taking the dividend as cash and taking it as additional units of the underlying instrument. Use DividendOptionEvent where the issuer creates new share capital in exchange for the dividend, and DividendReinvestmentEvent (DRIP) where the issuer instead invests the cash in the market on the holder's behalf.
The entitlement date is the exDate specified when you load DividendOptionEvent, not recordDate.
Amounts are calculated from the total number of instrument units held on the entitlement date, settled and unsettled.
Every DividendOptionEvent requires both a single CashElection and a single SecurityElection. The former establishes the dividend amount, and LUSID uses that amount to size the security leg, so you must supply the cash election even when taking units.
Where the security election is taken, LUSID rounds the new units down to a whole number. The leftover cash, being the difference between the dividend amount and the value of the units purchased, remains as a cash balance. There is no cash-in-lieu or buy-up outcome.
The two legs settle on different dates. The cash leg has a transaction date of exDate and a settlement date of paymentDate. The security leg has a transaction date of paymentDate and a settlement date of securitySettlementDate; if you do not set securitySettlementDate, LUSID uses paymentDate.

Loading `DividendOptionEvent`

You must load DividendOptionEvent into a corporate action source registered with one or more portfolios. The event then impacts every registered portfolio with a holding in the underlying instrument. See how to do this.

For more information on fields, see the DividendOptionEvent schema. Where set, the following date validation rules apply:
announcementDate ≤ exDate ≤ recordDate ≤ paymentDate

Only one participation type is valid, with two elections:

Participation type	Election(s)	Election choices	Further action required?
`MandatoryWithChoices`	Exactly one `CashElection`	Set the following: ✅ Is declared You can set the following if desired: ✅ Is chosen ✅ Is default	❓Optional. The Is Chosen election occurs unless you instruct to take the other leg per portfolio (see below).
Exactly one `SecurityElection`	Set the following: ❌ Is declared You can set the following if desired, but only if not set on `CashElection`: ✅ Is chosen ✅ Is default

Participation type

Election(s)

Election choices

Further action required?

MandatoryWithChoices

Exactly one CashElection

Set the following:

✅ Is declared

You can set the following if desired:

✅ Is chosen

✅ Is default

❓Optional. The Is Chosen election occurs unless you instruct to take the other leg per portfolio (see below).

Exactly one SecurityElection

Set the following:

❌ Is declared

You can set the following if desired, but only if not set on CashElection:

✅ Is chosen

✅ Is default

One election across both lists may be chosen, one may be declared, and one may be default. These need not be the same election: you can declare and default the cash leg while choosing the security leg, or vice versa. Note only the cash leg can be the declared election.

Note there is no lapse outcome; a holder who takes no action always receives the chosen leg rather than forfeiting the dividend.

Expressing the security election as a price or a ratio

Each SecurityElection needs to establish how many new units the dividend buys. Set either price (the price at which new units are issued) or unitsRatio (the number of new units issued per unit held). Supply one and LUSID calculates and returns the other for information.

For a dividend option the issuer is creating new share capital and typically announces a ratio, so unitsRatio is usually the natural input. LUSID then derives the price from the cash election's dividend rate. A price of 0 is not permitted. Where unitsRatio has an input equal to its output, the price is null.

Issuers often announce the reinvestment price or ratio after the event itself, so you may need to load the event first and update the election later.

Instructing to take a different leg per portfolio

If you want a particular portfolio to take the leg that is not chosen on the event, load an event instruction into that portfolio. Note this is not an event, and you do not load it into a corporate action source, which means you can instruct differently in different portfolios. See how to do this.

Configuring the economic impact

You must create some or all of the following transaction types to handle automatically-generated output transactions. They are not provided for you.

Transaction type (click for our recommendation)	Implement the transaction type if…	Intended economic impact
DvopCashIncome	Always required, whichever election is chosen	Credits the full dividend amount to a cash balance and reports it as income against the underlying instrument.
DvopSecurityOption	`SecurityElection` is chosen	Credits the new units and debits the cash that funded them.

Where the security election is chosen, both transactions are generated: the cash leg credits the whole dividend, and the security leg then spends part of it on units. The residue left by rounding units down stays in the cash balance.

You can give a transaction type any economic impact you like. Depending on the chosen election, our recommendations:

Create or update a cash holding in the dividend currency.
Report the cash as income using the ProfitAndLoss/Total/Other metric.
Do not change the units and cost of the underlying instrument on the cash leg, so ProfitAndLoss/Realised/* and ProfitAndLoss/Unrealised/* metrics are unchanged.
On the security leg, add the new units at the election price and remove the cash that funded them, so there is no ProfitAndLoss/Realised/Market impact at the point of reinvestment.

Reference example

In this example the issuer declares a dividend of 25 cents per unit, or one new unit for every 50 held. The cash election is chosen, so every registered portfolio with a holding on the ex-date receives cash unless instructed otherwise. LUSID calculates and returns a price of 12.50 on the security election.

[
  {
    "instrumentEventId": "DVOP-ACMECORP-2026",
    "instrumentIdentifiers": {
      "Instrument/default/ClientInternal": "ACMECORP-EQ"
    },
    "description": "Dividend option - Acme Corp (0.25 USD per unit in cash, or 1 new unit per 50 held)",
    "participationType": "MandatoryWithChoices",
    "instrumentEvent": {
      "instrumentEventType": "DividendOptionEvent",
      "announcementDate": "2026-08-01T00:00:00.0000000+00:00",
      "exDate": "2026-08-15T00:00:00.0000000+00:00",
      "recordDate": "2026-08-16T00:00:00.0000000+00:00",
      "paymentDate": "2026-09-01T00:00:00.0000000+00:00",
      "securitySettlementDate": "2026-09-04T00:00:00.0000000+00:00",
      "cashElections": [
        {
          "electionKey": "CASH",
          "dividendCurrency": "USD",
          "dividendRate": 0.25,
          "isDeclared": true,
          "isDefault": true,
          "isChosen": true
        }
      ],
      "securityElections": [
        {
          "electionKey": "SECU",
          "unitsRatio": {
            "input": 50,
            "output": 51
          },
          "isDefault": false,
          "isChosen": false
        }
      ]
    }
  }
]