--- title: "Modelling a bond drawing (DRAW)" slug: "modelling-a-drawing-draw" updated: 2026-11-18T11:21:13Z published: 2026-11-18T11:21:13Z canonical: "support.lusid.com/modelling-a-drawing-draw" --- > ## 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 bond drawing (DRAW) 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](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid). Note the following: - `DrawingEvent` is valid for instruments of type `Bond` and `ComplexBond`. - 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](/v1/docs/modelling-a-drawing-draw#instructing-the-affected-amount-per-holding). - The entitlement date is the `effectiveDate` (the lottery date) specified when you load `DrawingEvent`. - 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 `principal` for a `Bond`, and the current notional the day before `paymentDate` for a `ComplexBond`. - The cash amount is the affected amount × `pricePerUnit`, where `pricePerUnit` is the redemption price as a fraction of face (for example, `1.00` for 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](/v1/docs/how-do-i-upload-corporate-actions-to-a-corporate-action-source). For more information on fields, see the [DrawingEvent](https://www.lusid.com/docs/api/lusid/schemas/DrawingEvent/) schema. Where set, the following date validation rules apply: `effectiveDate ≤ paymentDate` > **Note**: `pricePerUnit` is 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? | | --- | --- | --- | --- | | `Mandatory` | N/A | N/A | ❓Depends. You must [instruct the affected amount for each drawn holding](/v1/docs/modelling-a-drawing-draw#instructing-the-affected-amount-per-holding), unless you set `affectedAmount` on the event itself. A holding with neither is unaffected, and no transaction is generated for it. | 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](/v1/docs/loading-an-event-instruction-to-override-an-instrument-event-for-a-particular-portfolio). Note the following: - The `instructionType` must be `ElectForHolding`, with `holdingId` set to the ID of the holding (returned by the [GetHoldings](https://www.lusid.com/api/swagger/index.html#/TransactionPortfolios/GetHoldings) API). - Set `quantityInstructed` to type `Units`, with `amount` set to the affected face amount. LUSID rejects a `Percentage` quantity, an `electionKey` and an `entitlementDateInstructed`. - 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. ```json curl -X POST 'https://.lusid.com/api/api/portfolios/FixedIncome/UK-Bonds/instrumenteventinstructions?successMode=Partial'  -H 'Content-Type: application/json-patch+json'  -H 'Authorization: Bearer '  -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](/v1/docs/recommended-transaction-types-for-corporate-action-events#drawingevent). 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/Market` [metric](/v1/docs/what-is-a-metric). ## 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. ```json [  {    "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. ```json [  {    "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.