Modelling unsupported corporate actions as transition events

LUSID is transitioning to a model where corporate actions have dedicated event types, for example CashDividendEvent, DividendReinvestmentEvent or AccumulationEvent. More information.

If an appropriate event type is not yet available, you can model any kind of corporate action as a TransitionEvent by considering the impact of inputs (the number and cost basis of units currently held) on outputs (the number and cost basis of future units, in the same instrument or in different ones).

Note: You might need to create multiple transition events to model some corporate actions.

A transition event must have:

A single input transition for the instrument that is the subject of the corporate action, with a units factor representing the number of units held and a cost factor representing the cost basis of those units.
One or more output transitions, each of which references a particular instrument (the same instrument, or a different one) and also has a units factor and a cost factor. The ratio of the two units factors determines the impact of the corporate action on the quantity of the holding, and the ratio of the two cost factors determines the impact of the corporate action on the cost basis of the holding.

Corporate action example (see also the examples in this Jupyter Notebook)	# of transition events	Input transition			Output transition(s)
	# of transition events	Instrument	Units factor	Cost factor	Instrument	Units factor	Cost factor
Cash dividend of 35p per share of Company A. See the example below.	1	Company A	1	0	GBP	0.35	0
2 for 1 stock split for Company A.	1	Company A	1	1	Company A	2	1
Spin off 1 new share in Company B for every 10 shares in Company A, taking 20% of the book cost.	1	Company A	10	1	Company A	10	0.8
	1	Company A	10	1	Company B	1	0.2
Takeover of Company A by Company B, replacing each Company A share with 0.8 share in Company B, plus 50p per share.	2	Company A	1	0	GBP	0.5	0
		Company A	1	1	Company A	0	0
		Company A	1	1	Company B	0.8	1

Example: Modelling a cash dividend as a transition event

The following call to the UpsertInstrumentEvents API uploads a corporate action representing a cash dividend of 35 cents per Company A share to a particular 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": "CompanyACashDividend-2023-02-13",
    "instrumentIdentifiers": {
      "Instrument/default/Figi": "BBG000BPH459"
    },
    "description": "Company A cash dividend of 35 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": "GBP"
          },
          "unitsFactor": 0.35,
          "costFactor": 0
        }
      ]
    }
  }
]'

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 an instrument representing Company A mastered 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 Company A share, and a costFactor of 0 since this corporate action does not impact the cost basis of these shares.
The single outputTransition impacts the GBP currency instrument, has a unitsFactor of 0.35 to represent the 35 cents per share, and a costFactor of 0.