Processing a corporate action representing a cash dividend

Views:

Related resources:

In this tutorial we'll see how to create a corporate action source, subscribe an existing transaction portfolio holding 1000 Microsoft shares to it, and upload a corporate action representing a cash dividend of $0.17 per Microsoft share.

Note that dates are important when considering corporate actions:

Ex-dividend date: We must hold Microsoft in our portfolio before this date for LUSID to automatically generate the 'output transactions' necessary to implement the corporate action, which in this case is a single transaction of $170.
Payment date: LUSID settles corporate actions on this date, which in this case increases the portfolio's USD cash balance by $170.

For a more detailed examination of cash dividends, and also other types of corporate action, see this Jupyter Notebook.

Section 1: Creating a corporate action source
Section 2: Subscribing a portfolio to the corporate action source
Section 3: Uploading a corporate action to the source
Section 4: Watching LUSID process the corporate action

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 our 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:

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, we can 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": "USD",
  "corporateActionSourceId": {
    "scope": "Example-CAS-scope",
    "code": "Example-CAS-code"
  },
  "subHoldingKeys": [],
  "instrumentScopes": [],
  "accountingMethod": "Default",
  "amortisationMethod": "NoAmortisation",
  ...
}

If we call the GetHoldings API for 12 February 2023, we can see that the portfolio has holdings in Microsoft and USD (the API 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 Microsoft cash dividend corporate action to the corporate action source. 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 in the LUSID Security Master.
The exDate is 13 February and the paymentDate is 17 February 2023. The other dates are informational.
The inputTransition has a unitsFactor of 1 to represent each Microsoft share, and a costFactor of 0 since this corporate action does not impact the cost basis of these shares (highlighted in red below).
The single outputTransition impacts the USD currency instrument, has a unitsFactor of 0.17 to represent the 17 cents per share, and a costFactor of 0 (highlighted in yellow).

See how to model other kinds of corporate action.

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-2023-02-13",
    "instrumentIdentifiers": {
      "Instrument/default/Figi": "BBG000BPH459"
    },
    "description": "Cash dividend of 17 cents per share",
    "instrumentEvent": {
      "instrumentEventType": "TransitionEvent",
      "announcementDate": "2023-02-01T00:00:00.0000000+00:00",
      "exDate": "2023-02-13T00:00:00.0000000+00:00",
      "recordDate": "2023-02-13T00:00:00.0000000+00:00",
      "paymentDate": "2023-02-17T00:00:00.0000000+00:00",
      "inputTransition": {
        "unitsFactor": 1,
        "costFactor": 0
      },
      "outputTransitions": [
        {
          "instrumentIdentifiers": {
            "Instrument/default/Currency": "USD"
          },
          "unitsFactor": 0.17,
          "costFactor": 0
        }
      ]
    }
  }
]'

Watching LUSID process the corporate action

If we call the GetHoldings API on 13 February 2023 (the exDate) we can see that LUSID has created a new, temporary, unsettled USD holding for $170 (1000 units * 0.17 cents per share), with a holding type of Accrual:

If we call the GetHoldings API on 17 February (the paymentDate) we can see that LUSID has settled the corporate action, removed the temporary holding, and updated the main USD holding by $170:

For audit purposes, we can call the BuildTransactions API with a suitable window to see the output transaction that LUSID generated to impact the holdings in this way:

Keywords: corporate action