Views:

In this tutorial we'll examine 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 with a particular scope and code by calling the CreateCorporateActionSource API, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -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 API to retrospectively subscribe an existing transaction portfolio to the corporate action source.

Note: You can subscribe a new portfolio when you create it.

For example, for a transaction portfolio with a scope of growth and a code of uk-equities (highlighted in red in the URL):

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/growth/uk-equities/details'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -d '{
  "corporateActionSourceId": {
    "scope": "Example-CAS-scope",
    "code": "Example-CAS-code"
  }
}'

To check the subscription, examine the response to the GetDetails API:

{
  "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 API on 1 February 2024 we can see that the portfolio has holdings in Microsoft and USD (the response has been transformed to a Pandas dataframe for clarity):

Uploading a corporate action to the source

We can call the UpsertInstrumentEvents API to upload our cash dividend corporate action for Microsoft to the corporate action source:

    curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources/Example-CAS-scope/Example-CAS-code/instrumentevents'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -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.
    • 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 (highlighted in red above). 
    • The chosen currency is GBP and the exchange rate is 0.8 (highlighted in green). 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 API to examine it:

    {
  "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: This template does not set the Transaction/default/TradeToPortfolioRate system property 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.

    In this tutorial we'll choose to use the default transaction template provided by LUSID, but you can create your own 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: Transaction types are grouped in sources and reside in scopes. For more information on the difference, see this article.

    In this example, we can call the SetTransactionType API as follows:

    curl -X PUT 'https://<your-domain>.lusid.com/api/api/transactionconfiguration/types/default/DividendIncome?scope=default'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -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 (highlighted in red in the URL above), to comply with the default transaction template.
    • You can design a transaction type to have any economic impact you like. This one has the following movements:
      • The first is a CashAccrual movement that maps gross dividend amounts to a CashDividends sub-holding key (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.
      • The second is a Carry movement that represents a flow of value out of the holding.
    • The Txn:TradeToPortfolioRate calculation 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:


    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:


    For audit purposes, we can call the BuildTransactions API with a suitable window to see the output transaction generated by LUSID in response to the cash dividend event. Note the transaction fields are populated as per the transaction template:

     

    Keywords: corporate action