--- title: "Handling a cash dividend corporate action event" slug: "handling-a-cash-dividend-corporate-action-event" updated: 2025-07-11T11:11:11Z published: 2025-07-11T11:11:11Z canonical: "support.lusid.com/handling-a-cash-dividend-corporate-action-event" --- > ## 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. # Handling a cash dividend corporate action event In this tutorial we'll examine [dedicated corporate action events](/v1/docs/understanding-dedicated-corporate-action-events) by using LUSID to perform the following task: **“I want to automate the process of handling cash dividends loaded into a corporate action source in order to reduce friction and improve efficiency.”** We'll see how to: 1. Create a corporate action source. 2. Subscribe an existing GBP-denominated transaction portfolio with a holding of 1000 Microsoft shares to the source. 3. Upload a corporate action of type `CashDividendEvent` representing a dividend of $0.20 per Microsoft share, electing to take it in GBP instead of USD at an exchange rate of 0.8. 4. Examine the default cash dividend transaction template provided by LUSID and choose to use rather then replace it. 5. Create a suitable transaction type to determine the economic impact of the transaction LUSID automatically generates in response to the event. 6. Watch LUSID process the corporate action on the ex-dividend and payment dates. Note that LUSID considers the following dates significant when processing corporate actions: - Ex-dividend date: We must hold Microsoft in our portfolio *before* this date for LUSID to emit the cash dividend event and trigger the transaction template to generate a transaction. - Payment date: LUSID settles the generated transaction on this date. ## Creating a corporate action source The first step is to create a [corporate action source](/v1/docs/how-do-i-create-a-corporate-action-source) with a particular scope and code by calling the [CreateCorporateActionSource](https://www.lusid.com/docs/api#operation/CreateCorporateActionSource) API, for example: ```json curl -X POST 'https://.lusid.com/api/api/corporateactionsources'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{    "scope": "Example-CAS-scope",    "code": "Example-CAS-code",    "displayName": "Example corporate action source",    "description": "This is an example corporate action source",  }' ``` ## Subscribing a portfolio to the corporate action source We can call the [UpsertPortfolioDetails](https://www.lusid.com/docs/api#operation/UpsertPortfolioDetails) API to retrospectively subscribe an existing transaction portfolio to the corporate action source. > [!NOTE] > **Note**: You can subscribe a new portfolio [when you create it](/v1/docs/how-do-i-create-a-transaction-portfolio). For example, for a transaction portfolio with a scope of `growth` and a code of `uk-equities` (in the URL): ```json curl -X POST 'https://.lusid.com/api/api/transactionportfolios/growth/uk-equities/details' -H 'Content-Type: application/json-patch+json' -H 'Authorization: Bearer ' -d '{  "corporateActionSourceId": {    "scope": "Example-CAS-scope",    "code": "Example-CAS-code"  } }' ``` To check the subscription, examine the response to the [GetDetails](https://www.lusid.com/docs/api#operation/GetDetails) API: ```json {  "originPortfolioId": {    "scope": "growth",    "code": "uk-equities"  },  "version": {    "effectiveFrom": "2022-01-01T00:00:00.0000000+00:00",    "asAtDate": "2023-03-04T12:41:02.5737930+00:00"  },  "baseCurrency": "GBP",  "corporateActionSourceId": {    "scope": "Example-CAS-scope",    "code": "Example-CAS-code"  },  "subHoldingKeys": [],  "instrumentScopes": [],  "accountingMethod": "Default",  "amortisationMethod": "NoAmortisation",  "transactionTypeScope": "Default",  "cashGainLossCalculationDate": "Default",  "instrumentEventConfiguration": {    "transactionTemplateScopes": ["default"]  },  ... } ``` If we call the [GetHoldings](https://www.lusid.com/docs/api#operation/GetHoldings) API on 1 February 2024 we can see that the portfolio has holdings in Microsoft and USD (the response has been transformed to a table for clarity): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(58).png) ## Uploading a corporate action to the source We can call the [UpsertInstrumentEvents](https://www.lusid.com/docs/api#operation/UpsertInstrumentEvents) API to upload our cash dividend corporate action for Microsoft to the corporate action source: ```json curl -X POST 'https://.lusid.com/api/api/corporateactionsources/Example-CAS-scope/Example-CAS-code/instrumentevents' -H 'Content-Type: application/json-patch+json' -H 'Authorization: Bearer ' -d '[  {    "instrumentEventId": "MSCashDividend-2024-02-06",    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},    "description": "Cash dividend of 20 cents per share",    "participationType": "MandatoryWithChoices",    "instrumentEvent": {      "instrumentEventType": "CashDividendEvent",      "announcementDate": "2024-01-01T00:00:00.0000000+00:00",      "exDate": "2024-02-06T00:00:00.0000000+00:00",      "recordDate": "2024-02-10T00:00:00.0000000+00:00",      "paymentDate": "2024-02-10T00:00:00.0000000+00:00",      "cashElections": [        {          "electionKey": "USD",          "dividendCurrency": "USD",          "dividendRate": "0.2",          "isDeclared": "True",          "isChosen": "False",          "isDefault": "True",        },        {          "electionKey": "GBP",          "dividendCurrency": "GBP",          "exchangeRate": "0.8",          "isDeclared": "False",          "isChosen": "True",          "isDefault": "False",        }      ]    }  } ]' ``` Note the following: - The `instrumentEventId` is a free string field that must uniquely identify this corporate action in the corporate action source. - The `instrumentIdentifiers` field uses a FIGI to resolve to a Microsoft instrument mastered in the LUSID Security Master, but you could specify any unique identifier. - The participation type is `MandatoryWithChoices` to allow elective currencies. There must be one declared election and one chosen election. The default setting is `Mandatory`, in which case there can only be a declared election. [More on multiple cash elections](/v1/docs/understanding-participation-types-and-elections-for-corporate-actions#specifying-multiple-cash-elections). - The ex-dividend date is 6 February and the payment date is 10 February 2024. The other dates are informational. - The instrument event type is `CashDividendEvent` to cause LUSID to emit an event of this type on the ex-dividend date. - The declared currency is USD and the dividend rate is expressed as a number, so for example 20% as 0.2. - The chosen currency is GBP and the exchange rate is 0.8. LUSID automatically calculates the GBP dividend rate from the USD dividend rate multiplied by the exchange rate, so in this case 0.2 * 0.8 = 0.16. ## Examining the default transaction template for cash dividend events LUSID provides a default *cash dividend transaction template* that is triggered whenever a cash dividend event is emitted to generate a suitable cash dividend transaction. We can call the [GetTransactionTemplate](https://www.lusid.com/docs/api#operation/GetTransactionTemplate) API to examine it: ```json {  "instrumentType": "Equity",  "instrumentEventType": "CashDividendEvent",  "description": "LUSID default template for automatically generated transactions in respect of Cash Dividend (DVCA) instrument events.",  "scope": "default",  "componentTransactions": [    {      "displayName": "Dividend Income",      "transactionFieldMap": {        "transactionId": "{{instrumentEventId}}-{{holdingId}}",        "type": "DividendIncome",        "source": "default",        "instrument": "{{instrument}}",        "transactionDate": "{{CashDividendEvent.exDate}}",        "settlementDate": "{{CashDividendEvent.paymentDate}}",        "units": "{{eligibleBalance}}",        "transactionPrice": {          "price": "{{CashDividendEvent.DeclaredElection.dividendRate}}",          "type": "CashFlowPerUnit"        },        "transactionCurrency": "{{CashDividendEvent.DeclaredElection.dividendCurrency}}",        "exchangeRate": "{{CashDividendEvent.ChosenElection.exchangeRate}}",        "totalConsideration": {          "currency": "{{CashDividendEvent.ChosenElection.dividendCurrency}}",          "amount": "{{CashDividendEvent.ChosenElection.dividendAmount}}"        }      }    }  ],  ... } ``` Note the following: - This template is for corporate action events of type `CashDividendEvent` for instruments of type `Equity`. Note this event is also available for `SimpleInstrument`. - It is domiciled in the `default` (that is, system) transaction template scope. - It generates a single transaction for each portfolio with a holding in the underlying instrument. Note it is possible for a template to generate multiple transactions. - The transaction has no `condition`; that is, it is always produced when LUSID emits a cash dividend event. - The transaction belongs to a `DividendIncome` transaction type, which must reside in the `default` transaction type source. - The transaction date is the ex-dividend date and the settlement date is the payment date. - The quantity held is assessed dynamically per-portfolio. - The transaction price is the dividend rate of the declared currency. - The settlement currency is the chosen currency (determined by the `exchangeRate` field set to the rate of the chosen currency). - The total consideration is the dividend rate of the chosen currency (automatically calculated by LUSID) scaled by the quantity held. > [!NOTE] > **Note**: This template does not set the `Transaction/default/TradeToPortfolioRate` [system property](/v1/docs/what-is-a-system-property#transaction-system-properties) to calculate the cost basis of the output transaction in the portfolio currency, in circumstances where this is different to the transaction currency. The recommended mechanism is to use a combination of a modified transaction type and a recipe to look up an exchange rate for the transaction date in the LUSID Quote Store dynamically. [See how to do this](/v1/docs/transactions-and-exchange-rates#looking-up-exchange-rates-dynamically-using-a-recipe). In this tutorial we'll choose to use the default transaction template provided by LUSID, but you can [create your own custom transaction template](/v1/docs/how-do-i-create-a-custom-transaction-template) to override the default template and configure the process if you wish. Note you *must* create a custom transaction template if you want to nominate a different transaction type. ## Creating a suitable transaction type for cash dividend output transactions The default transaction template mandates a `DividendIncome` transaction type grouped in the `default` transaction type source. We must create this transaction type if it does not exist. > [!NOTE] > **Note**: Transaction types are grouped in *sources* and reside in *scopes*. For more information on the difference, see [this article](/v1/docs/grouping-related-transaction-types-using-scopes-and-sources). In this example, we can call the [SetTransactionType](https://www.lusid.com/docs/api#operation/SetTransactionType) API as follows: ```json curl -X PUT 'https://.lusid.com/api/api/transactionconfiguration/types/default/DividendIncome?scope=default'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -d '{  "aliases": [    {      "type": "DividendIncome",      "description": "Type for cash dividend event",      "transactionClass": "Basic",      "transactionRoles": "AllRoles",      "isDefault": false    }  ],  "movements": [    {      "movementTypes": "CashAccrual",      "side": "Side2",      "direction": 1,      "mappings": [        {          "propertyKey": "Transaction/SHKs/CashDividends",          "setTo": "CashDividends"        }      ],      "name": "Add cash dividend to separate portfolio cash balance"    },    {      "movementTypes": "Carry",      "side": "Side1",      "direction": 1,      "name": "Report the dividend as a flow out of the investment"    }  ],  "calculations": [    {      "type": "Txn:TradeToPortfolioRate"    }  ] }' ``` Note the following: - The transaction type alias is `DividendIncome`, to comply with the default transaction template. - The transaction type source is `default` (in the URL above), to comply with the default transaction template. - You can design a transaction type to have [any economic impact you like](/v1/docs/what-is-a-transaction-type). This one has the following [movements](/v1/docs/what-movement-types-are-available): - The first is a `CashAccrual` movement that maps gross dividend amounts to a `CashDividends` [sub-holding key](/v1/docs/what-is-a-sub-holding-key-shk) (SHK), to report accrual separately to other cash holdings in the chosen currency (GBP). You could omit the `mappings` array to add coupons to the main GBP cash holding instead. [See how to calculate a net amount after tax](/v1/docs/introduction-to-tax-calculations-in-lusid). - The second is a `Carry` movement that represents a flow of value out of the holding. - The `Txn:TradeToPortfolioRate` [calculation type](/v1/docs/what-is-a-transaction-type) looks up an exchange rate from the transaction to the portfolio currency dynamically, if different. ## Watching LUSID process the corporate action If we call the `GetHoldings` API on 6 February 2024 (the ex-dividend date) we see that LUSID has created a new, temporary unsettled cash holding for £160 with a holding type of `Accrual`: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(49).png) If we call the `GetHoldings` API on 10 February (the payment date) we see that all units are now settled and the holding type is `Balance`: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(50).png) For audit purposes, we can call the [BuildTransactions](https://www.lusid.com/docs/api#operation/BuildTransactions) API with a suitable window to see the [output transaction](/v1/docs/input-and-output-transactions) generated by LUSID in response to the cash dividend event. Note the transaction fields are populated as per the transaction template: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(51).png)