--- title: "Modelling a stock split (SPLF)" slug: "modelling-a-stock-split-splf" updated: 2026-11-18T14:18:52Z published: 2026-11-18T14:18:52Z canonical: "support.lusid.com/modelling-a-stock-split-splf" --- > ## 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 a stock split (SPLF) You can model a stock split, where a company divides its shares into more shares with a proportionally lower price, as a corporate action of type `StockSplitEvent` in LUSID. [See all supported corporate actions](/v1/docs/understanding-dedicated-corporate-action-events). Note the following: - `StockSplitEvent` is valid for instruments of type `Equity`, `SimpleInstrument`, `PreferredShare`, `ContractForDifference`, `EquityOption` and `ExchangeTradedOption`. - By default the holding stays in the same instrument and its number of units rises. If the split also issues a new instrument, for example a new ISIN, you can [move the holding to it](/v1/docs/modelling-a-stock-split-splf#moving-the-holding-to-a-new-instrument). - The entitlement date is the `exDate` specified when you load `StockSplitEvent`. - The additional units are calculated from the total number of instrument units held on the entitlement date, settled and unsettled: (`output` ÷ `input` − 1) × units held. - LUSID adds the additional units at zero cost, so the holding's total cost is unchanged and its cost per unit falls. - A split can leave a holder entitled to a fraction of a unit. You can [pay cash for the fraction, or have the holder buy the rest of a whole unit](/v1/docs/modelling-a-stock-split-splf#handling-fractional-units). - In a portfolio that tracks tax lots, LUSID adds units to each lot separately, so each lot keeps its own cost. - The transaction date of the automatically-generated additional units is `exDate`, and the settlement date is `paymentDate`. The cash-in-lieu and buy-up transactions are dated `paymentDate`. ## Loading `StockSplitEvent` You must load `StockSplitEvent` into a corporate action source registered with one or more portfolios. The event then impacts every registered portfolio with a holding in the underlying instrument. [See how to do this](/v1/docs/how-do-i-upload-corporate-actions-to-a-corporate-action-source). For more information on fields, see the [StockSplitEvent](https://www.lusid.com/docs/api/lusid/schemas/StockSplitEvent/) schema. Where set, the following date validation rules apply: `exDate ≤ paymentDate` > **Note**: `output` must be greater than `input`. By default the ratio is the total number of units held after the split: a 10-for-1 split is `{"input": 1, "output": 10}`. If your data provider quotes the additional units instead, set `unitScaleType` to `ADEX`: the same split is `{"input": 1, "output": 9, "unitScaleType": "ADEX"}`. Only one participation type is valid, and there are no elections: | Participation type | Election(s) | Election choices | Further action required? | | --- | --- | --- | --- | | `Mandatory` | N/A | N/A | ❌ No. The split always occurs automatically. | ## Handling fractional units LUSID adds the full entitlement, including any fraction of a unit. To pay cash for the fraction instead, set `fractionalUnitsCashPrice` (the price per post-split unit) and `fractionalUnitsCashCurrency`. If you set neither, the fraction stays in the holding. If you set only one, LUSID marks the event as incomplete. To change how the fraction is rounded, set `fractionalUnitsRoundingConvention`. This requires `fractionalUnitsCashPrice`: | Rounding convention | Units kept and cash | | --- | --- | | `Floor` (the default) | Rounds down to a whole unit. The holder receives cash in lieu for the fraction. | | `RoundHalfUp`, `RoundHalfDown`, `BankerRounding` | Rounds to the nearest whole unit, treating an exact half as the name suggests (`BankerRounding` rounds a half to the nearest even unit). Cash in lieu if rounded down. If rounded up, the fraction currently stays in the holding. | | `RoundToDecimalPlaces` | Rounds to the number of decimal places in `fractionalUnitsDecimalPlaces`. Cash in lieu for any remainder rounded away. | | `Ceiling` | Intended to round up to a whole unit at no cost. LUSID currently leaves the fraction in the holding and generates no cash. | | `BuyUp` | Rounds up to a whole unit, and the holder pays for the rest of the unit at `fractionalUnitsCashPrice`. | ## Moving the holding to a new instrument Some splits retire the original instrument and issue a new one in its place, for example a new ISIN on a change of face value. To model this, set `newInstrument` to the identifiers of the new instrument. You must master the new instrument in LUSID first. Until LUSID can resolve it, the event is incomplete and generates no transactions. Instead of adding units, LUSID then closes the whole holding in the original instrument and opens the post-split holding in the new one: (`output` ÷ `input`) × units held. Both transactions carry the holding's cost, lot by lot. Any cash in lieu or buy-up applies to the new instrument. ## Configuring the economic impact You must create some or all of the following transaction types to handle automatically-generated output transactions. They are not provided for you. | Transaction type (click for our recommendation) | Implement the transaction type if… | Intended economic impact | | --- | --- | --- | | [StockSplitAdditionalUnits](/v1/docs/recommended-transaction-types-for-corporate-action-events#stocksplitadditionalunits-transaction-type) | The event doesn't set `newInstrument` | Adds units to the holding without changing its total cost. | | [StockSplitCashInLieu](/v1/docs/recommended-transaction-types-for-corporate-action-events#stocksplitcashinlieu-transaction-type) | A fraction is rounded away, and the event sets `fractionalUnitsCashPrice` and `fractionalUnitsCashCurrency` | Sells the fraction for cash. | | [StockSplitBuyUp](/v1/docs/recommended-transaction-types-for-corporate-action-events#stocksplitbuyup-transaction-type) | The event sets `fractionalUnitsRoundingConvention` to `BuyUp` | Buys the rest of a whole unit for cash. | | [StockSplitSubstitutionClose](/v1/docs/recommended-transaction-types-for-corporate-action-events#stocksplitsubstitutionclose-transaction-type) | The event sets `newInstrument` | Removes the holding in the original instrument at its cost. | | [StockSplitSubstitutionOpen](/v1/docs/recommended-transaction-types-for-corporate-action-events#stocksplitsubstitutionopen-transaction-type) | The event sets `newInstrument` | Adds the post-split holding in the new instrument at the same cost. | You can give a transaction type any economic impact you like. Our recommendation: - Adds units at zero cost, so the total cost stays the same and the cost per unit falls. - Sells any fraction for cash in lieu, realising a small gain or loss against the fraction's share of the cost. - Creates or updates a cash holding in the `fractionalUnitsCashCurrency` for any cash in lieu or buy-up. - Moves the cost to the new instrument unchanged when the split issues a new instrument, so nothing is realised. ## Reference examples ### A split with cash in lieu A company splits every two shares into three. Fractions are paid in cash at 6.00 GBP per post-split share. ```json [  {    "instrumentEventId": "SPLF-ACMECORP-2026",    "instrumentIdentifiers": {      "Instrument/default/ClientInternal": "ACMECORP-EQ"    },    "description": "Stock split - Acme Corp, 3 new shares for every 2 held",    "participationType": "Mandatory",    "instrumentEvent": {      "instrumentEventType": "StockSplitEvent",      "exDate": "2026-09-01T00:00:00.0000000+00:00",      "paymentDate": "2026-09-08T00:00:00.0000000+00:00",      "unitsRatio": { "input": 2, "output": 3 },      "fractionalUnitsCashPrice": 6.00,      "fractionalUnitsCashCurrency": "GBP"    }  } ] ``` A portfolio holding 101 shares at a cost of 1,010.00 GBP is entitled to 50.5 additional shares. LUSID generates additional units of 50.5 shares at zero cost on 1 September 2026, and a cash-in-lieu transaction selling 0.5 shares for 3.00 GBP on 8 September 2026. With our recommended transaction types, the holding ends at 151 shares with a cost of 1,006.67 GBP, and the sale of the fraction realises a loss of 0.33 GBP. ### A split with buy-up The same terms, but the holder buys the rest of a whole share. ```json [  {    "instrumentEventId": "SPLF-ACMECORP-2026-BUYUP",    "instrumentIdentifiers": {      "Instrument/default/ClientInternal": "ACMECORP-EQ"    },    "description": "Stock split - Acme Corp, 3 for 2, fractions bought up",    "participationType": "Mandatory",    "instrumentEvent": {      "instrumentEventType": "StockSplitEvent",      "exDate": "2026-09-01T00:00:00.0000000+00:00",      "paymentDate": "2026-09-08T00:00:00.0000000+00:00",      "unitsRatio": { "input": 2, "output": 3 },      "fractionalUnitsCashPrice": 6.00,      "fractionalUnitsCashCurrency": "GBP",      "fractionalUnitsRoundingConvention": "BuyUp"    }  } ] ``` The same portfolio receives 50.5 additional shares and a buy-up transaction of 0.5 shares for 3.00 GBP. The holding ends at 152 shares with a cost of 1,013.00 GBP, and nothing is realised. ### A split that issues a new instrument A company splits every share into two and issues a new ISIN for the post-split shares. The new instrument is already mastered in LUSID. ```json [  {    "instrumentEventId": "SPLF-ACMECORP-2026-NEWISIN",    "instrumentIdentifiers": {      "Instrument/default/ClientInternal": "ACMECORP-EQ"    },    "description": "Stock split - Acme Corp, 2 for 1 with a new ISIN",    "participationType": "Mandatory",    "instrumentEvent": {      "instrumentEventType": "StockSplitEvent",      "exDate": "2026-09-01T00:00:00.0000000+00:00",      "paymentDate": "2026-09-08T00:00:00.0000000+00:00",      "unitsRatio": { "input": 1, "output": 2 },      "newInstrument": {        "instrumentIdentifiers": {          "Instrument/default/ClientInternal": "ACMECORP-EQ-NEW"        }      }    }  } ] ``` A portfolio holding 100 shares at a cost of 1,000.00 GBP receives two transactions on 1 September 2026, both settling on 8 September 2026. The first closes the 100 shares in `ACMECORP-EQ` at a cost of 1,000.00 GBP. The second opens 200 shares in `ACMECORP-EQ-NEW` at the same cost. Nothing is realised.