---
title: "Modelling a cash dividend (DVCA)"
slug: "modelling-a-cash-dividend-dvca"
updated: 2026-09-01T12:27:27Z
published: 2026-09-01T12:27:27Z
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 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](/v1/docs/modelling-a-cash-dividend-dvca#splitting-a-payment-by-rate-type) (for example, franked and unfranked), each generating its own tagged transaction.

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

## 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](/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`

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

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

Issuers specify multi-currency offers in different ways. [See how to handle multiple cash elections](/v1/docs/understanding-participation-types-and-elections-for-corporate-actions#specifying-multiple-cash-elections).

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

## 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](/v1/docs/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](/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.

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.

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

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