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.

What is a settlement instruction?

  • Updated on Jun 8, 2026
  • Published on Sep 17, 2025
Prev Next

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

A SI 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, though note 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 a 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, and 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 always loads and may appear to succeed when in fact it doesn’t (click to enlarge):

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:

You can examine the status in the Settlements dialog immediately after you create a settlement instruction for a transaction:

© 2025 FINBOURNE Technology