---
title: "What is a settlement instruction?"
slug: "loading-settlement-instructions"
updated: 2026-06-08T08:02:33Z
published: 2026-06-08T08:02:33Z
canonical: "support.lusid.com/loading-settlement-instructions"
---

> ## 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?

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](/v1/docs/loading-settlement-instructions#checking-settlement-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.

LUSID web appLUSID API

Call the [UpsertSettlementInstructions](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/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.

```json
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):

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-GOAU3FG4.png)

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):

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-UT5LD13N.png)

## 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):

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image (29).png)

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.

LUSID web appLUSID API

Call the [GetTransactionSettlementStatus](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/GetTransactionSettlementStatus) API for a transaction and examine the `status` field for the instruction:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-5L5UXJ1V.png)

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

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-EOJV6ILN.png)