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

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.

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.

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`.	Credits additional units of either the underlying instrument (`SecurityOfferElection`) or a new instrument (`MixedLotConstituentsElection`) at zero cost.
BonusIssueCashInLieu	`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	`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	`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, 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.

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

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.

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

Documentation Index