---
title: "Modelling unsupported corporate actions as transition events"
slug: "modelling-unsupported-corporate-actions-as-transition-events"
updated: 2024-11-28T19:15:47Z
published: 2024-11-28T19:15:47Z
canonical: "support.lusid.com/modelling-unsupported-corporate-actions-as-transition-events"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v1/docs/understanding-dedicated-corporate-action-events).

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](https://github.com/finbourne/finbourne-notebooks/blob/main/V1/examples/use-cases/ibor/Corporate%20Actions.ipynb)) | **# 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](https://www.lusid.com/docs/api#operation/UpsertInstrumentEvents) API uploads a corporate action representing a cash dividend of 35 cents per Company A share to a particular corporate action source:

```json
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.