How do I manually adjust or set holdings?

  • Updated on Jul 4, 2025
  • Published on Aug 20, 2024
Prev Next

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
    Recommended. 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.

Whether you set or adjust holdings:

  • The value you are setting is:

    • The Units field for security holdings (holding type of Position), which is the total number of settled and unsettled units. This is the trade date holdings.

    • The Settled Units field for currency holdings (holding type of Cash Balance), since unsettled cash positions are reported as separate temporary holdings (holding types of either Cash Commitment, Cash Accrual, Cash Receivable or Forward FX). This is the settlement day holdings.

  • Any unsettled transactions that exist on the effective date of the set or adjustment continue to update the appropriate Cash Balance holding on their settlement date.

  • LUSID automatically generates ‘true up’ output transactions representing the difference between the before and after states. These have transaction types of either AdjustmentIncrease and AdjustmentDecrease which are not currently configurable.

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:

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:

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:

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

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 trade date basis (unsettled) units, 0 settled units and a cost of £1000

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

If we want to update the BP trade date basis units to 110 on 2 February we can call the BatchAdjustHoldings API to adjust only the BP holding to 110 shares @ £11. Note the following:

  • The BP holding now has 110 trade date basis 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:

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: