How do I manually adjust or set holdings?

  • Updated on Mar 3, 2025
  • Published on Aug 20, 2024

The standard way to update a portfolio is to book transactions and ask LUSID to generate holdings on demand. However, if you do not have a suitable feed of transactions, you can set holdings directly.

For each holding, the instrument, unit, cost and any properties are stored against the specified effective date. Any subsequent transactions impacting the holding (that is, those with a transaction date after the effective date) continue to impact it in the normal way.

The following APIs are available:

  • SetHoldings
    Replaces all the current holdings in the portfolio with the supplied set. Any holdings in any instruments not included in the request are removed (that is, reduced to zero).

  • AdjustHoldings
    Updates the current holdings in the portfolio with the supplied set, all of which must share the same effective date. Any holdings in instruments that are not included in the request are left untouched.

  • BatchAdjustHoldings
    As per AdjustHoldings, except holdings in the supplied set can have different effective dates, and you can choose a success mode to decide whether or not the entire operation fails if one holding fails validation.

Whether you set or adjust holdings, there is no profit and loss (P&L) associated with the event. For instance, if your initial holding is 5,000 BP shares at a price of £10 a share, your initial cost is £50,000. If you then adjust the BP holding to 4,000 shares and change the price to £9 a share, your initial cost becomes £36,000; there is no gain or loss associated with this adjustment, even if the adjustment is booked to a different effective date. 

The primary use of this capability is to ensure that holdings in LUSID can match an external system, even if the external system is unable to provide a comprehensive transaction history.

Note the following:

  • Holdings can be adjusted at the instrument and sub-holding level within a portfolio, so you can change the tax lot or strategy holdings.

  • If you adjust holdings and add or update properties, any properties not included in the request are left untouched.

  • If you set and adjust holdings at the exact same time, the set operation is executed first and then adjusted by the adjust operation.

Understanding how LUSID implements holding adjustments

Whether you set or adjust holdings, LUSID automatically generates output transactions representing the difference between the before and after states.

Example 1: Setting or adjusting settled holdings

Consider the following example of a portfolio with two holdings, generated by booking a standard Buy transaction for 100 BP shares @ £10 a share on 1 February, settling on 3 February. The before state at EOD 3 February is therefore:

  • A BP holding with 100 settled units at a cost of £1000

  • A GBP currency holding with -1000 settled units at a cost of -£1000:

4 February

Imagine on 4 February we call the BatchAdjustHoldings API to adjust only the BP holding to 110 shares @ £11. Note the following:

  • The BP holding now has 110 settled units at a cost of £1210

  • The GBP holding is unchanged, since only the BP holding was adjusted:

To account for the difference between the two states, LUSID generates an AdjustmentIncrease output transaction for 10 units of BP with a total consideration of £210:

5 February

Imagine on 5 February we call the BatchAdjustHoldings API again to set the BP holding to 90 shares @ £9. Note the following:

  • The BP holding now has 90 settled units at a cost of £810

  • The GBP holding is unchanged, since only the BP holding was adjusted:

To account for the difference, LUSID generates an AdjustmentDecrease output transaction for 20 units of BP with a total consideration of -£400:

6 February

Imagine on 6 February we call the SetHoldings API to set the BP holding to 120 shares @ £12. Note the following:

  • The BP holding now has 120 settled units at a cost of £1440

  • The GBP holding has been removed, since this API replaces any holdings in the portfolio that are not explicitly set:

To account for the difference, LUSID generates two output transactions:

  • An AdjustmentIncrease output transaction for 30 units of BP with a total consideration of £630

  • An AdjustmentIncrease output transaction for 1000 units of GBP with a total consideration of £1000 (to true up to zero):

Note: The behaviour of the AdjustmentIncrease and AdjustmentDecrease transaction types is built in to LUSID and not currently configurable.

Example 2: Setting or adjusting unsettled holdings

Consider the same example of a portfolio with two holdings, generated by booking a standard Buy transaction for 100 BP shares @ £10 a share on 1 February, settling on 3 February. The before state at EOD 1 February is therefore:

  • A BP holding with 100 unsettled units, 0 settled units and a cost of £1000

  • A GBP currency holding with -1000 unsettled units, 0 settled units and a cash commitment of -£1000:

2 February

Imagine we call the BatchAdjustHoldings API on 2 February to adjust only the BP holding to 110 shares @ £11. Note the following:

  • The BP holding now has 110 unsettled units, 10 settled units and a cost of £1210

  • The GBP holding is not impacted, since only the BP holding was adjusted:

To account for the difference between the two states, LUSID generates an AdjustmentIncrease output transaction for 10 units of BP with a total consideration of £210. Since this ‘transaction’ trades and settles immediately, these 10 units are settled units:

3 February

If we audit holdings on 3 February we can see that the original 100 units of BP and -1000 units of GBP have now also settled: