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.

Note the following:

BonusIssueEvent is valid for instruments of type Equity and SimpleInstrument.
A bonus issue credits existing holders with additional units of the same instrument, free of payment, in proportion to their holding. No new instrument is involved, so BonusIssueEvent has no newInstrument field.
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.
BonusIssueEvent requires exactly one SecurityOfferElection, even when the participation type is Mandatory and the holder has nothing to choose. LUSID reads the bonus ratio from that election's unitsRatio, so you must always supply it.
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 all output transactions is paymentDate.

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.

For more information on fields, see the BonusIssueEvent schema. Where set, the following date validation rules apply:
announcementDate ≤ exDate ≤ recordDate ≤ paymentDate

You must choose one of the following participation types:

Participation type	Election(s)	Election choices	Further action required?
`Mandatory`	Exactly one `SecurityOfferElection`, carrying the bonus `unitsRatio`.	Set the following on the single election: ✅ Is chosen ✅ Is default	❌ No. The single election always occurs automatically.
`MandatoryWithChoices`	Exactly one `SecurityOfferElection`, one `CashOfferElection` and one `LapseElection`, each with a unique key.	The above options must be set but can be in any combination on any election.	❓Optional. The Is chosen election occurs unless you instruct to take a different election per portfolio (see below).

Participation type

Election(s)

Election choices

Further action required?

Mandatory

Exactly one SecurityOfferElection, carrying the bonus unitsRatio.

Set the following on the single election:

✅ Is chosen

✅ Is default

❌ No. The single election always occurs automatically.

MandatoryWithChoices

Exactly one SecurityOfferElection, one CashOfferElection and one LapseElection, each with a unique key.

The above options must be set but can be in any combination on any election.

❓Optional. The Is chosen election occurs unless you instruct to take a different election per portfolio (see below).

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 does have a lapse outcome. If LapseElection is the chosen election, LUSID generates no transactions at all and the holding is unchanged.

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.

Rounding convention	Outcome
`Floor` (the default)	LUSID rounds the entitlement down to a whole number of units and sells the fractional remainder for cash, generating a `BonusIssueCashInLieu` transaction.
`BuyUp`	LUSID rounds the entitlement up to the next whole unit and the portfolio purchases the shortfall, generating a `BonusIssueBuyUp` transaction. This is a genuine cash outflow.

Both outcomes require you to set fractionalUnitsCashPrice and fractionalUnitsCashCurrency on the event. If either is missing, neither transaction is generated and the fractional remainder is simply not settled.

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.

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	The chosen election is not `LapseElection`. Under `Mandatory` participation this transaction is always generated.	Credits additional units of the underlying instrument at a cost of zero.
BonusIssueCashInLieu	`SecurityOfferElection` 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	`SecurityOfferElection` 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	`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 the underlying instrument at zero cost on the additional units leg.
Report cash-in-lieu proceeds as a realised gain using the ProfitAndLoss/Realised/Market 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 mechanical 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.

[
  {
    "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.

[
  {
    "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
        }
      ]
    }
  }
]

Documentation Index