Views:

Note: This tutorial uses the new, dedicated CashDividendEvent corporate action event. Contact us to turn this feature on in your LUSID environment. Alternatively, you can continue modelling a cash dividend as a transition event

In this tutorial 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 the transaction type stipulated by the transaction template to determine the economic impact of the transaction LUSID 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 dividends

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

    We'll choose to use the default template as-is but you can replace it with a custom template if you wish. See how to do this (coming soon).
     

    Understanding the default transaction type for cash dividend

    LUSID provides a default cash dividend transaction type that is invoked by the default transaction template to determine the economic impact of cash dividend transactions. We can call the GetTransactionType API to examine it:

    {
      "aliases": [
        {
          "type": "DividendIncome",
          "description": "Type for cash dividend event",
          "transactionClass": "Basic",
          "transactionRoles": "AllRoles",
          "isDefault": false
        }
      ],
      "movements": [],
      "properties": {},
      "calculations": [],
    }

    Note the following:

    • By design, the default transaction type has no movements, and therefore no economic impact. This is to prevent cash dividend events impacting existing portfolios in an uncontrolled manner.
    • The transaction type has a single alias of DividendIncome.
    • It resides in the default transaction type scope and default transaction type source. More information on scopes and sources.

    Creating an impactful transaction type for cash dividends

    We can either:

    • Overwrite the default cash dividend transaction type (above) to add movements representing our desired impact for cash dividend transactions.
    • Create a new transaction type with the same alias residing in a different transaction type scope, and configure portfolios to reference that scope.

    In this tutorial, we'll use the SetTransactionType API to overwrite the default cash dividend transaction type 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",
        }
      ]
    }'

    Note the following:

    • The transaction type alias remains DividendIncome, so it will be invoked by the transaction template.
    • It has two movements to impact any portfolio with a holding in the underlying instrument as follows:
      • The first is a CashAccrual movement that maps the gross dividend amount to a sub-holding key (SHK), to report it separately to any main cash balance in the chosen currency. 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.

    Note: You can configure a transaction type to have any economic impact you like. More information.
     

    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: