--- title: "Modelling a bonus issue (BONU)" slug: "modelling-a-bonus-issue-bonu" updated: 2026-09-02T12:43:50Z published: 2026-09-02T12:43:50Z canonical: "support.lusid.com/modelling-a-bonus-issue-bonu" --- > ## 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 bonus issue (BONU) You can model a bonus issue as a corporate action of type `BonusIssueEvent` in LUSID. [See all supported corporate actions](/v1/docs/understanding-dedicated-corporate-action-events). Note the following: - `BonusIssueEvent` is valid for instruments of type `Equity` and `SimpleInstrument`. - A bonus issue credits existing holders with additional securities, free of payment, in proportion to their holding. The original position is always retained; a bonus issue never debits the underlying holding. - Every `BonusIssueEvent` requires exactly one of the following (although you may choose to take cash instead): - A `SecurityOfferElection` crediting additional units of the same instrument. - A `MixedLotConstituentsElection` crediting one or more [distinct new securities](/v1/docs/modelling-a-bonus-issue-bonu#crediting-new-securities-instead-of-additional-units) alongside the retained original position. - The entitlement date is the `exDate` specified when you load `BonusIssueEvent`, not `recordDate`. - Amounts are calculated from the total number of instrument units held on the entitlement date, settled and unsettled. - The transaction date of the automatically-generated `BonusIssueAdditionalUnits` output transaction is `exDate`. The transaction date of other output transactions is `paymentDate`. The settlement date of output transactions is `paymentDate` except in the case of mixed lot constituents, when it is specified per constituent. ## Loading `BonusIssueEvent` You must load `BonusIssueEvent` 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 [BonusIssueEvent](https://www.lusid.com/docs/api/lusid/schemas/BonusIssueEvent/) schema. The following date validation rules apply: `exDate ≤ paymentDate` You must choose **one** of the following participation types. Note `Voluntary` is invalid. | Participation type | Election(s) | Election choices | Further action required? | | --- | --- | --- | --- | | `Mandatory` | Either: - One `SecurityOfferElection`, or - One `MixedLotConstituentsElection` `CashOfferElection` and `LapseElection` are rejected. | Set the following on the single election: ✅ **Is chosen** ✅ **Is default** | ❌ No. The single, chosen election always occurs automatically. | | `MandatoryWithChoices` | Exactly one entitlement election (as above), plus at most one `CashOfferElection` and at most one `LapseElection`, each with a unique key. You must supply at least two elections in total. | Across the set of elections: - Exactly one must be **Is default**. - At most one may be **Is chosen**. If none, the default election applies. | ❓Optional. The **Is chosen** or **Is default** election occurs unless you [instruct to take a different election per portfolio](/v1/docs/modelling-a-bonus-issue-bonu#instructing-to-take-a-different-election-per-portfolio). | Note that none of these election types has an **Is declared** option; only **Is chosen** and **Is default** apply. Unlike a cash dividend, a bonus issue loaded as `MandatoryWithChoices` has a lapse outcome. If `LapseElection` is the chosen election, LUSID generates no transactions at all and the holding is unchanged. ## Crediting new securities instead of additional units Most bonus issues credit more of the instrument already held, which you model with a `SecurityOfferElection`. Where the issuer instead distributes one or more *different* securities — for example a new class of share, or a package of several instruments — use a `MixedLotConstituentsElection` instead. Set `securitiesConstituents` on the election, with one entry per security to be credited. Each entry specifies: | Field | Purpose | | --- | --- | | `newInstrument` | Identifies the security to credit. Required. | | `unitsRatio` | The entitlement ratio for this security, expressed as `input` (units held) to `output` (units received). Required, and set per constituent, so each security can be distributed on its own ratio. | | `settlementDate` | The settlement date for this security. Required, and set per constituent, so constituents can settle on different dates. | | `minPieceSize`, `minIncrement` | Optional constraints on the distributable quantity of this security. | The election itself also has an optional `costFactor`. Note the following: - A `MixedLotConstituentsElection` on a `BonusIssueEvent` may only carry securities. If you set `cashConstituents`, LUSID rejects the event: because the underlying position is retained, there is no disposition for a cash constituent to attach to. To offer cash as an *alternative* to the entitlement, use a `CashOfferElection` under `MandatoryWithChoices` instead. - You cannot combine a `MixedLotConstituentsElection` and a `SecurityOfferElection` on the same event. Exactly one of the two must describe the entitlement. ## Handling fractional units A bonus ratio rarely divides a real holding into whole units. Where `SecurityOfferElection` is the chosen election, `fractionalUnitsRoundingConvention` determines what happens to the remainder. It defaults to `Floor`. All conventions require you to set `fractionalUnitsCashPrice` and `fractionalUnitsCashCurrency` on the event. If either is missing, no transactions are generated and the fractional remainder is simply not settled. | Rounding convention | Outcome | | --- | --- | | `Floor` (the default) | Rounds down to the nearest whole unit and sells the fractional remainder for cash, generating a `BonusIssueCashInLieu` transaction. | | `BuyUp` | Rounds up to the nearest whole unit and the portfolio purchases the shortfall, generating a `BonusIssueBuyUp` transaction. This is a genuine cash outflow. | | `Ceiling` | Rounds up to the nearest whole unit at no cost (no cash movement). | | `RoundHalfUp` | If the fraction is equal to or greater than half, rounds up to the nearest whole unit at no cost (no cash movement). If less, rounds down and sells the fractional remainder for cash, generating a `BonusIssueCashInLieu` transaction. | | `RoundHalfDown` | If the fraction is greater than half, rounds up to the nearest whole unit at no cost (no cash movement). If equal to or less than half, rounds down and sells the fractional remainder for cash, generating a `BonusIssueCashInLieu` transaction. | | `BankerRounding` | As per the rounding conventions above, but a fraction of exactly half rounds either up or down to an even number, so for example both 1.5 and 2.5 round to 2. | | `RoundToDecimalPlaces` | Rounds to the number of decimal places specified by the `fractionalUnitsDecimalPlaces` field. The fractional remainder is sold for cash, generating a `BonusIssueCashInLieu` transaction. | ## Instructing to take a different election per portfolio If you load `BonusIssueEvent` as `MandatoryWithChoices`, you can instruct a particular portfolio to take an election other than the chosen one. If you do not, the portfolio takes the chosen election. To do this, load an *event instruction* into a portfolio. Note this is not an event, and you do not load it into a corporate action source, which means you can instruct differently in different portfolios. [See how to do this](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio). ## 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 | Implement the transaction type if… | Intended economic impact | | --- | --- | --- | | [BonusIssueAdditionalUnits](/v1/docs/recommended-transaction-types-for-corporate-action-events#bonusissueevent) | The chosen election is not `LapseElection`. | Credits additional units of either the underlying instrument (`SecurityOfferElection`) or a new instrument (`MixedLotConstituentsElection`) at zero cost. | | [BonusIssueCashInLieu](/v1/docs/recommended-transaction-types-for-corporate-action-events#bonusissuecashinlieu-transaction-type) | `SecurityOfferElection` or `MixedLotConstituentsElection` is chosen, there are fractional units remaining, and the loaded event sets: - `fractionalUnitsCashPrice ≠ null` - `fractionalUnitsCashCurrency ≠ null` | Settles a fractional remainder in cash if `fractionalUnitsRoundingConvention ≠ BuyUp`. | | [BonusIssueBuyUp](/v1/docs/recommended-transaction-types-for-corporate-action-events#bonusissuebuyup-transaction-type) | `SecurityOfferElection` or `MixedLotConstituentsElection` is chosen, there are fractional units remaining, and the loaded event sets: - `fractionalUnitsRoundingConvention = BuyUp` - `fractionalUnitsCashPrice ≠ null` - `fractionalUnitsCashCurrency ≠ null` | Rounds a fractional remainder up to a full unit and settles the price difference in cash. | | [BonusIssueCashOffer](/v1/docs/recommended-transaction-types-for-corporate-action-events#bonusissuecashoffer-transaction-type) | `CashOfferElection` is chosen. | Credits cash for the whole entitlement, at the election's `cashOfferPrice` per unit held, instead of crediting units. | You can give a transaction type any economic impact you like. Depending on the chosen election, our recommendations: - Add units to an instrument at zero cost on the additional units leg. - Report cash-in-lieu proceeds as a realised gain using the `ProfitAndLoss/Realised/Market` [metric](/v1/docs/what-is-a-metric), since the fractional units sold carry no cost. - On the buy-up leg, add the units at the fractional cash price and remove the cash that funded them, so there is no `ProfitAndLoss/Realised/Market` impact. - Report cash offer proceeds as a realised gain using the `ProfitAndLoss/Realised/Market` metric. The entitlement was never held, so the whole receipt is a gain. > **Note**: The additional units leg has a total consideration of zero, and LUSID does not currently re-allocate any cost from the existing holding onto the new units. The cost of the underlying holding is therefore unchanged, and average cost per unit falls as a consequence of the higher unit count. Support for redistributing cost basis across the enlarged holding is planned for a future release. ## Reference examples ### Mandatory bonus issue The issuer declares one bonus unit for every ten held. Participation is `Mandatory`, so every registered portfolio with a holding on the ex-date receives the additional units. Any fractional remainder is sold at 1.80 GBP per unit under the default `Floor` convention. ```json [  {    "instrumentEventId": "BONU-ACMECORP-2026",    "instrumentIdentifiers": {      "Instrument/default/ClientInternal": "ACMECORP-EQ"    },    "description": "Bonus issue - Acme Corp (1 new unit for every 10 held)",    "participationType": "Mandatory",    "instrumentEvent": {      "instrumentEventType": "BonusIssueEvent",      "announcementDate": "2026-07-15T00:00:00.0000000+00:00",      "exDate": "2026-08-01T00:00:00.0000000+00:00",      "recordDate": "2026-08-02T00:00:00.0000000+00:00",      "paymentDate": "2026-08-08T00:00:00.0000000+00:00",      "fractionalUnitsCashPrice": 1.80,      "fractionalUnitsCashCurrency": "GBP",      "securityOfferElections": [        {          "electionKey": "SECU",          "isDefault": true,          "isChosen": true,          "unitsRatio": { "input": 10, "output": 11 }        }      ]    }  } ] ``` A portfolio holding 10,000 units on 1 August 2026 receives 1,000 additional units, settling on 8 August 2026, at a total consideration of zero. ### Bonus issue with choices The same bonus issue is offered with a choice: take the units, take 2.00 GBP per unit held in cash instead, or decline. The security election is chosen, so portfolios receive units unless instructed otherwise. ```json [  {    "instrumentEventId": "BONU-ACMECORP-2026-CHOICES",    "instrumentIdentifiers": {      "Instrument/default/ClientInternal": "ACMECORP-EQ"    },    "description": "Bonus issue - Acme Corp (units, cash alternative, or decline)",    "participationType": "MandatoryWithChoices",    "instrumentEvent": {      "instrumentEventType": "BonusIssueEvent",      "exDate": "2026-08-01T00:00:00.0000000+00:00",      "paymentDate": "2026-08-08T00:00:00.0000000+00:00",      "fractionalUnitsCashPrice": 1.80,      "fractionalUnitsCashCurrency": "GBP",      "fractionalUnitsRoundingConvention": "BuyUp",      "securityOfferElections": [        {          "electionKey": "SECU",          "isDefault": true,          "isChosen": true,          "unitsRatio": { "input": 10, "output": 11 }        }      ],      "cashOfferElections": [        {          "electionKey": "CASH",          "isDefault": false,          "isChosen": false,          "cashOfferPrice": 2.00,          "cashOfferCurrency": "GBP"        }      ],      "lapseElections": [        {          "electionKey": "NOAC",          "isDefault": false,          "isChosen": false        }      ]    }  } ] ``` ### Bonus issue of new securities The issuer distributes a package of two different securities rather than more of the instrument held: one B-class share for every twenty held, and one warrant for every fifty held, settling on different dates. The original holding is retained in full. ```json [  {    "instrumentEventId": "BONU-ACMECORP-2026-MIXEDLOT",    "instrumentIdentifiers": {      "Instrument/default/ClientInternal": "ACMECORP-EQ"    },    "description": "Bonus issue - Acme Corp (B-class shares and warrants)",    "participationType": "Mandatory",    "instrumentEvent": {      "instrumentEventType": "BonusIssueEvent",      "exDate": "2026-08-01T00:00:00.0000000+00:00",      "paymentDate": "2026-08-08T00:00:00.0000000+00:00",      "mixedLotConstituentsElections": [        {          "electionKey": "MIXED",          "isDefault": true,          "isChosen": true,          "securitiesConstituents": [            {              "newInstrument": {                "instrumentIdentifiers": {                  "Instrument/default/ClientInternal": "ACMECORP-EQ-B"                }              },              "unitsRatio": { "input": 20, "output": 1 },              "settlementDate": "2026-08-08T00:00:00.0000000+00:00"            },            {              "newInstrument": {                "instrumentIdentifiers": {                  "Instrument/default/ClientInternal": "ACMECORP-WARRANT"                }              },              "unitsRatio": { "input": 50, "output": 1 },              "settlementDate": "2026-08-15T00:00:00.0000000+00:00"            }          ]        }      ]    }  } ] ``` A portfolio holding 10,000 units on 1 August 2026 receives 500 B-class shares settling on 8 August 2026 and 200 warrants settling on 15 August 2026, and retains its 10,000 original units.