What is a settlement instruction?

  • Updated on Apr 13, 2026
  • Published on Sep 17, 2025
Prev Next

A settlement instruction (SI) settles some or all units for a particular transaction in a portfolio.

A settlement instruction must identify a category (or ‘bucket’) of either stock, cash or deferred cash. Typically, a category equates to a single movement generated by the original transaction type but there are circumstances in which a category equates to more than one movement.

A SI that passes basic API validation is always accepted by LUSID but may not actually succeed. See how to check instruction status.

Loading a settlement instruction

Note the following:

  • A SI must have an ID that is unique among all SIs loaded into the portfolio.

  • You can specify any number of units up to the total number to settle.

  • The units should have the same sign, so if the number of unsettled units is -500 then the SI must also settle a negative number.

Call the UpsertSettlementInstructions API. Note the following:

  • The settlementCategory must be either StockSettlement, CashSettlement or DeferredCashSettlement.

  • If you omit instructionType it defaults to Partial. This can be used for both partial and complete settlement, although Complete is also a valid value. The third option is CancelAutomatic for cancelling automatic settlement.

curl -X POST "https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/UK-Growth/settlementinstructions"
 -H "Authorization: Bearer <your-API-access-token>"
 -H "Content-Type: application/json-patch+json"
 -d '[
  {
    "settlementInstructionId": "Settle-Txn01-10-Sep-2025",
    "transactionId": "Txn01",
    "settlementCategory": "CashSettlement",
    "instructionType": "Partial",
    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "CCY_GBP"},
    "actualSettlementDate": "2025-09-10T00:00:00.0000000+00:00",
    "units": -500
  }
]'

Navigate to the Data Management > Holdings dashboard, click the Units field of the holding to settle (in yellow) and then click the Transaction settlements button for the source transaction (in green):

Then, in the Settlements dialog for the source transaction, click the appropriate Create settlement button (in yellow below) and complete the form (making sure Amount to settle has the same sign as Unsettled amount, in this case negative):

Checking settlement instruction status

We strongly recommend checking settlement instruction status. The instruction may load and appear to succeed when it in fact it hasn’t:

Common causes of a Rejected status are:

  • You specify an instructionType of Complete but then fewer than the total number of unsettled units.

  • You specify a number of units to settle that do not have the same sign as the unsettled units.

Call the GetTransactionSettlementStatus API for a transaction and examine the status field for the instruction:

Examine the status in the Settlements dialog immediately after you create a settlement instruction for a transaction:

© 2025 FINBOURNE Technology