Modelling a cash dividend (DVCA)

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

Note the following:

CashDividendEvent is valid for instruments of type Equity, SimpleInstrument and FundShareClass.
The entitlement date is the exDate specified when you load CashDividendEvent, not recordDate.
The dividend amount is calculated from the total number of instrument units held on the entitlement date, settled and unsettled.
The transaction date of automatically-generated output transactions is exDate, and the settlement date is paymentDate.
Optionally, a single election can carry a breakdown of tax-characterised payout lines (for example, franked and unfranked), each generating its own tagged transaction.

Recommended tutorial: Handling a cash dividend corporate action

Loading `CashDividendEvent`

You load CashDividendEvent 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 CashDividendEvent schema. Where set, the following date validation rules apply:
announcementDate ≤ exDate ≤ recordDate ≤ paymentDate

Note: You can set paymentDate at event level, at election level, or both. The election-level date takes precedence. At least one must resolve, or LUSID rejects the event.

You must choose one of the following participation types:

Participation type	Election(s)	Election choices	Further action required?
`Mandatory`	Exactly one `CashElection` keyed by currency	Set the following on the single election: ✅ Is chosen ✅ Is declared ✅ Is default	❌ No. The single election always occurs automatically.
`MandatoryWithChoices`	At least one `CashElection`, each keyed by (the different) currency	The above options must be set but can be in any combination on any election.	❓Optional. The Is Chosen election occurs unless you instruct to receive a different currency per portfolio (see below).

Participation type

Election(s)

Election choices

Further action required?

Mandatory

Exactly one CashElection keyed by currency

Set the following on the single election:

✅ Is chosen
✅ Is declared
✅ Is default

❌ No. The single election always occurs automatically.

MandatoryWithChoices

At least one CashElection, each keyed by (the different) currency

The above options must be set but can be in any combination on any election.

❓Optional. The Is Chosen election occurs unless you instruct to receive a different currency per portfolio (see below).

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

Instructing to receive a different currency per portfolio

If you load CashDividendEvent as MandatoryWithChoices, you can instruct to receive the dividend in a different currency. If you do not, you receive the chosen election currency.

To do this, load an event instruction into a 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.

Splitting a payment by rate type

Some dividends are announced as a single option with a breakdown of tax-characterised components, most commonly franked and unfranked in Australia, or PID and non-PID for UK REITs. Rather than splitting these into separate events, you can add an optional rateBreakdown to a CashElection. The event continues to mirror the market announcement, and LUSID generates a separately-tagged transaction for each component.

Each breakdown line has two fields:

rateType — a free-string code, maximum 50 characters, such as UNFR, FLFR or PID.
dividendRate — the per-unit amount for that line, in the election's dividendCurrency.

Note the following:

Lines inherit the election's dividendCurrency and effective payment date. You cannot set a currency or date on an individual line.
The sum of the lines must not exceed the election's dividendRate. If the lines sum to less, LUSID posts the difference as one additional standard, untagged dividend transaction.
LUSID tags each breakdown transaction with the Transaction/default/RateType system property, enabling you to trigger different tax calculations. There is no cap on the number of lines.
If the chosen currency differs from the declared currency, each line and any remainder scale by the election's exchangeRate.
rateBreakdown can only be specified on the declared election, but LUSID processes it on the chosen election as normal. If you omit it, LUSID generates one standard dividend transaction exactly as before.

LUSID validates the breakdown as follows:

Condition	Behaviour
`rateBreakdown` absent or empty	LUSID generates one standard dividend transaction. This is the default behaviour.
Lines sum to less than the election `dividendRate`	LUSID generates one tagged transaction per line, plus one standard untagged transaction for the difference.
Lines sum exactly to the election `dividendRate`	LUSID generates one tagged transaction per line, with no remainder.
Lines sum to more than the election `dividendRate`	LUSID rejects the event, returning both the sum of the lines and the election rate.
`rateType` missing or blank	LUSID rejects the event, returning the position of the offending line.
A currency or date supplied on an individual line	LUSID rejects the event. Lines inherit both from the election.
No payment date resolves at either election or event level	LUSID rejects the event.

Configuring the economic impact

You must create a DividendIncome transaction type to handle the automatically-generated output transaction. This is not provided for you. See our recommendation.

You can give a transaction type any economic impact you like. Our recommendation:

Creates or updates a cash holding in the chosen currency.
Reports the cash as income using the ProfitAndLoss/Total/Other metric.
Does not change the units and cost of the underlying instrument, so ProfitAndLoss/Realised/* and ProfitAndLoss/Unrealised/* metrics are unchanged.

If you use rateBreakdown, the same DividendIncome transaction type handles every generated transaction. The breakdown changes how many transactions LUSID generates, not their economic impact. To apply different tax treatment per component, create a tax ruleset that matches on the Transaction/default/RateType property.

Reference examples

Multi-currency dividend

A USD dividend of 0.20 per share is announced. Three elections are specified; the GBP election is chosen at a USDGBP exchange rate of 0.79 unless overridden per portfolio by an event instruction.

[
  {
    "instrumentEventId": "MSCashDividend-2026-08-15",
    "instrumentIdentifiers": {
      "Instrument/default/Figi": "BBG000BPH459"
    },
    "description": "Cash dividend of 20 cents per Microsoft share, paid in GBP by default",
    "participationType": "MandatoryWithChoices",
    "instrumentEvent": {
      "instrumentEventType": "CashDividendEvent",
      "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",
      "cashElections": [
        {
          "electionKey": "USDollar",
          "dividendCurrency": "USD",
          "dividendRate": "0.2",
          "isDeclared": true,
          "isDefault": true,
          "isChosen": false
        },
        {
          "electionKey": "GreatBritishPounds",
          "dividendCurrency": "GBP",
          "exchangeRate": "0.79",
          "isDeclared": false,
          "isDefault": false,
          "isChosen": true
        },
        {
          "electionKey": "Euro",
          "dividendCurrency": "EUR",
          "exchangeRate": "1.08",
          "isDeclared": false,
          "isDefault": false,
          "isChosen": false
        }
      ]
    }
  }
]

Dividend with a rate breakdown

An AUD dividend of 0.0410 per share is announced as 0.0363 unfranked plus 0.0047 fully franked. A portfolio holds 1,000,000 units on the entitlement date. LUSID generates two transactions, both settling on 16 March 2026:

AUD 36,300, tagged UNFR.
AUD 4,700, tagged FLFR.

Because the lines sum exactly to 0.0410, there is no remainder. Had only the UNFR line been supplied, LUSID would also have posted a third, untagged transaction for AUD 4,700.

[
  {
    "instrumentEventId": "CashDividend-2026-02-20",
    "instrumentIdentifiers": {
      "Instrument/default/Figi": "BBG000BR0L98"
    },
    "description": "AUD cash dividend, 0.0363 unfranked + 0.0047 fully franked",
    "participationType": "Mandatory",
    "instrumentEvent": {
      "instrumentEventType": "CashDividendEvent",
      "exDate": "2026-02-20T00:00:00.0000000+00:00",
      "recordDate": "2026-02-21T00:00:00.0000000+00:00",
      "paymentDate": "2026-03-15T00:00:00.0000000+00:00",
      "cashElections": [
        {
          "electionKey": "AUD",
          "dividendCurrency": "AUD",
          "dividendRate": 0.0410,
          "paymentDate": "2026-03-16T00:00:00.0000000+00:00",
          "isDeclared": true,
          "isChosen": true,
          "isDefault": true,
          "rateBreakdown": [
            { "rateType": "UNFR", "dividendRate": 0.0363 },
            { "rateType": "FLFR", "dividendRate": 0.0047 }
          ]
        }
      ]
    }
  }
]

Documentation Index