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) | ||||
| 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 |
| 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 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
instrumentEventIdis a free string field that must uniquely identify this corporate action in the corporate action source. - The
instrumentIdentifiersfield uses a FIGI to resolve to an instrument representing Company A mastered in the LUSID Security Master. - The
exDateis 13 February and thepaymentDateis 17 February 2023. The other dates are informational. - The
inputTransitionhas aunitsFactorof 1 to represent each Company A share, and acostFactorof 0 since this corporate action does not impact the cost basis of these shares (highlighted in red). - The single
outputTransitionimpacts the GBP currency instrument, has aunitsFactorof 0.35 to represent the 35 cents per share, and acostFactorof 0 (highlighted in yellow).