---
title: "Modelling a cash dividend (DVCA)"
slug: "modelling-a-cash-dividend-dvca"
updated: 2026-08-04T11:33:52Z
published: 2026-08-04T11:33:52Z
canonical: "support.lusid.com/modelling-a-cash-dividend-dvca"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v1/docs/understanding-dedicated-corporate-action-events).

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 the automatically-generated output transaction is `exDate`, and the settlement date is `paymentDate`.

**Recommended tutorial**: [Handling a cash dividend corporate action](/v1/docs/handling-a-cash-dividend-corporate-action-event)

## Loading `CashDividendEvent`

You must 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](/v1/docs/how-do-i-upload-corporate-actions-to-a-corporate-action-source).

For more information on fields, see the [CashDividendEvent](https://www.lusid.com/docs/api/lusid/schemas/CashDividendEvent/) schema. Where set, the following date validation rules apply: `announcementDate ≤ exDate ≤ recordDate ≤ paymentDate`

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

Note there is no silent lapse outcome; a holder who takes no action always receives the chosen 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](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio).

## 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](/v1/docs/recommended-transaction-types-for-corporate-action-events#cashdividendevent).

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](/v1/docs/what-is-a-metric).
- Does not change the units and cost of the underlying instrument, so `ProfitAndLoss/Realised/*` and `ProfitAndLoss/Unrealised/*` metrics are unchanged.

## Reference example

```json
[
  {
    "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.20",
          "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"
        }
      ]
    }
  }
]
```