You can model a drawing, where an issuer redeems part of a bond issue early and selects the bonds to redeem by lottery, as a corporate action of type DrawingEvent in LUSID. See all supported instrument events.
Note the following:
DrawingEventis valid for instruments of typeBondandComplexBond.Unlike a partial call, a drawing does not affect every holder in proportion. The issuer's lottery might redeem all of one holding, part of another and none of a third. LUSID does not run the lottery: you tell LUSID the affected face amount (AFFB), usually by instructing it per holding.
The entitlement date is the
effectiveDate(the lottery date) specified when you loadDrawingEvent.The affected amount is a face amount, not a number of units. LUSID divides it by the principal per unit to find the units to redeem: the
principalfor aBond, and the current notional the day beforepaymentDatefor aComplexBond.The cash amount is the affected amount ×
pricePerUnit, wherepricePerUnitis the redemption price as a fraction of face (for example,1.00for par). This is a clean price; LUSID does not pay accrued interest on the drawn bonds.The transaction date and settlement date of the automatically-generated output transaction are both
paymentDate.The units that are not drawn are unaffected, and continue to receive coupons and redeem at maturity as normal.
Loading DrawingEvent
You must load DrawingEvent 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 DrawingEvent schema. Where set, the following date validation rules apply:effectiveDate ≤ paymentDate
Note:
pricePerUnitis optional when you load the event, because the issuer often announces the affected amounts before the redemption price. LUSID generates no transaction until you add it.
Only one participation type is valid, and there are no elections:
Participation type | Election(s) | Election choices | Further action required? |
|---|---|---|---|
| N/A | N/A | ❓Depends. You must instruct the affected amount for each drawn holding, unless you set |
If you set affectedAmount on the event, LUSID applies the same face amount to every holding in the instrument, in every registered portfolio. This is rarely correct for a drawing, so use it only when you know one figure applies to every holding. An instruction for a holding takes precedence over the event-level amount.
Instructing the affected amount per holding
For each holding the lottery selected, load an event instruction carrying that holding's affected face amount. Note this is not an event, and you do not load it into a corporate action source, which means you can instruct a different amount for each holding. See how to do this.
Note the following:
The
instructionTypemust beElectForHolding, withholdingIdset to the ID of the holding (returned by the GetHoldings API).Set
quantityInstructedto typeUnits, withamountset to the affected face amount. LUSID rejects aPercentagequantity, anelectionKeyand anentitlementDateInstructed.If the instructed amount is more than the holding's settled face on the entitlement date, LUSID accepts the instruction but generates no transaction for the holding. Check the amount against the holding before you load it.
curl -X POST 'https://<your-domain>.lusid.com/api/api/portfolios/FixedIncome/UK-Bonds/instrumenteventinstructions?successMode=Partial'
-H 'Content-Type: application/json-patch+json'
-H 'Authorization: Bearer <your-API-access-token>'
-d '{
"draw-1": {
"instrumentEventInstructionId": "draw-1",
"instrumentEventId": "DRAW-ACMECORP-2031",
"instructionType": "ElectForHolding",
"holdingId": 86787124,
"quantityInstructed": {"type": "Units", "amount": 2000000}
}
}'Configuring the economic impact
You must create a BondDrawing transaction type to handle the automatically-generated output transaction. This is not provided for you. See our recommendation.
You can give a transaction type any economic impact you like. Our recommendation:
Removes the drawn units from the bond holding, and reduces its cost in proportion.
Creates or updates a cash holding in the settlement currency.
Reports the difference between the cash received and the cost of the drawn units as a realised gain or loss, using the
ProfitAndLoss/Realised/Marketmetric.
Reference examples
A drawing instructed per holding
An issuer draws bonds for redemption at par. The event carries no affected amount, so each drawn holding must be instructed.
[
{
"instrumentEventId": "DRAW-ACMECORP-2031",
"instrumentIdentifiers": {
"Instrument/default/ClientInternal": "ACMECORP-BOND-2031"
},
"description": "Drawing - Acme Corp 2031 bond, redeemed at par",
"participationType": "Mandatory",
"instrumentEvent": {
"instrumentEventType": "DrawingEvent",
"effectiveDate": "2026-09-01T00:00:00.0000000+00:00",
"paymentDate": "2026-09-15T00:00:00.0000000+00:00",
"pricePerUnit": 1.00,
"currency": "GBP"
}
}
]A portfolio holds 100,000 units of the bond, with a principal of 100 per unit (GBP 10,000,000 face), bought at 98 (a cost of GBP 9,800,000). The lottery selects GBP 2,000,000 of its face, so the holding is instructed with an affected amount of 2,000,000. On 15 September 2026,
LUSID generates one BondDrawing transaction for 20,000 units (2,000,000 ÷ 100) with a total consideration of GBP 2,000,000.00 (2,000,000 × 1.00). The holding falls to 80,000 units at a cost of GBP 7,840,000, and the portfolio realises a gain of GBP 40,000 (2,000,000 − 1,960,000). A portfolio holding the same bond but not instructed is unaffected.
A drawing applied to every holding
The same affected amount applies to every holding, so it is set on the event and no instructions are needed. The bonds are redeemed at 99.
[
{
"instrumentEventId": "DRAW-ACMECORP-2031-B",
"instrumentIdentifiers": {
"Instrument/default/ClientInternal": "ACMECORP-BOND-2031-B"
},
"description": "Drawing - Acme Corp 2031 B bond, GBP 500,000 face per holding at 99",
"participationType": "Mandatory",
"instrumentEvent": {
"instrumentEventType": "DrawingEvent",
"effectiveDate": "2026-09-01T00:00:00.0000000+00:00",
"paymentDate": "2026-09-15T00:00:00.0000000+00:00",
"affectedAmount": 500000,
"pricePerUnit": 0.99,
"currency": "GBP"
}
}
]A portfolio holding 50,000 units of the bond (principal 100 per unit) bought at 100 receives a BondDrawing transaction for 5,000 units with a total consideration of GBP 495,000.00 (500,000 × 0.99), and realises a loss of GBP 5,000.