Order

This page contains all relevant terminology regarding Orders.

Order

Definition

An Order is a command to execute changes in the Assets that are possessed by an Investor. Orders are executed on the next trading day after they have been approved. This means that the Assets to be purchased or sold in this Order will be traded for a different price than the price of that Asset on the day of placing the Order.

Relevant endpoints

• POST /Orders
• GET /OrderGetById/{labelId}/{orderId}
• GET /OrderFormDataGetById/{labelId}/{orderId}
• GET /OrderFormDataGetByInvestorAccountId/{labelId}/{investorAccountId}
• PUT /OrderCancelById/{labelId}/{orderId}
• GET /OrderGetOrderTotalByLabelIdAndMarketDayId/{labelId}
• POST /OrderAdd
• POST /OrderAddMigrated
• POST /OrderAddMultipleMigrated
• PUT /OrderUpdate
• PUT /OrderReverse
• POST /OrderCorrectionAdd
• GET /OrderReasons/{labelId}
• PUT /OrderCalculate
• POST /OrderReasonAdd

OrderType

Definition

The different types of Orders are:

• Regular (buy/sell units of one Asset).
• Switch (trade units of one Asset for units of another Asset, where the sale and purchase of both Assets happen on the same ~TradingDate~ and the same Market and are ~ValueBased~).
• IndirectSwitch (trade units of one Asset for units of another Asset, where the purchase of the latter Asset happens the trading day after the sale of the former so that it is certain how much units can be bought without having to pay extra or not having spent all revenue from the sale).
• ReInvest (when receiving Dividends, these can immediately be reinvested into the same Asset from which the Dividends were received or into another Asset).
• Refund (correcting an Investor’s Cash balance after a failed direct debit by reimbursing the corresponding Order’s value).
• AssetMix (buying an AssetMix.
• ProRata (selling some units of the Assets in each AssetMixRecord so that their percentages within an AssetMix at that moment stay the same).
• Rebalance (Rebalances an AssetMix.

OrderTrade

Definition

An Order consists of one or more OrderTrades. Each OrderTrade represents the sale or purchase of units of one specific Asset. For an AssetMix Order, for example, the Assets in each AssetMixRecord will be bought in a separate OrderTrade.

OrderTradeType

Definition

Either ‘Buy’ or ‘Sell’.

OrderTradeExecutionType

Definition

An OrderTrade can be executed in two ways:

• ValueBased (the amount of money that is to be spent is specified in the Order upon its creation. Upon execution of the Order, the number of units of an Asset that can be bought with this amount of money is computed).
• UnitBased (for OrderTradeType ‘Sell’ only. The number of units of an Asset that are to be sold is specified in the Order upon its creation. Upon execution of the Order, it is computed how much money will be received because of the Order).

OrderTradePriceType

Definition

The OrderTradePriceType of an OrderTrade is automatically determined based on the OrderTradeType and OrderTradeExecutionType (it cannot be set by Investors). It determines how many units of an Asset will be bought/sold because of this OrderTrade. As it is already clear what the number of units will be in a unit based OrderTrade, OrderTradePriceTypes apply only to value based OrderTrades. A value based OrderTrade can have two price types:

• Gross (applicable for OrderTradeType ‘Buy’. When buying units of an Asset for a specified gross amount of money, the transaction fee of the OrderTrade will be deducted from this gross amount. This results in the net value of the OrderTrade, from which can be computed how many units of the Asset can be bought).
• Net (applicable for OrderTradeType ‘Sell’. When selling units of an Asset to receive a desired net amount specified in the OrderTrade, the transaction fee of this OrderTrade is covered by selling a certain amount of units extra. The gross value of the OrderTrade in this case equals the desired, net amount plus the transaction fee).

The combination of the OrderTradeType and OrderTradeExecutionType attributes already implies what the OrderTradePriceType is, but for legacy reasons and flexibility purposes (some Labels may want to separately charge their fees, for example) this is still a separate attribute.

OrderTradeCosts

Definition

The fees associated with executing an Order. The ~EstimatedCosts~ are based on the price of the Asset on the day of creating the Order and the ~ChargedCosts~ are based on the price of the Asset on the actual trading day.

OrderTradeState

Definition

OrderTrades have different States depending on where they are in the ~Approval~ process

• Created (upon creation of the Order).
• ReserveForOrder (Cash or Assets are being reserved for the OrderTrade).
• NoCashAvailable (if there is not enough cash available for buying the desired Asset, currently not in use).
• Pending (waiting for the cutoff time to pass. The Order can still be changed up to and including this state).
• LockedForProcess (when the cutoff time has passed, the Order is now locked for changes).
• WaitingForCostsCalculated (waiting for the OrderTrade’s costs to be calculated).
• WaitingForPortfolio (only for OrderTradeType ‘Sell’, waiting for confirmation that there are enough units of a certain Asset available in the portfolio to be able to sell the desired number of units).
• WaitingForTrade (waiting until the moment of actually trading).
• Processed (the OrderTrade has been fully processed).
• Cancelled (the OrderTrade has been cancelled before it got to the ‘LockedForProcess’ state).
• ReadyForPayout (only for OrderTradeType ‘Sell’, occurs when the sell has been confirmed by the receival of a corresponding CamtFile).
• Reversed (the Order has been reversed, see ‘OrderReversal’).

OrderReason

Definition

Can be optionally specified for every Order.

Relevant endpoints

• GET /OrderReasons/{labelId}
• POST /OrderReasonAdd

OrderReference

Definition

Orders can be referenced to from other entities. For this purpose, they are assigned a ~ReferenceId~ that can be used in other microservices.

CreateSepaRecords

Definition

For every Order it is specified whether a SEPA record (which leads to a payout) should be created. This attribute can only be ‘true’ for Orders of OrderType ‘Sell’, however. If it is not set to ‘true’, the sell value of the Order is added to the main Cash Ledger of the InvestorAccount. This can be the case, for example, for a BOX1 InvestorAccount (see: ‘FiscalPolicy’) from which the Investor is not allowed to withdraw funds until their retirement.

TradeSafetyMargin

Definition

For ~ValueBased~ OrderTrades with the type ‘Sell’, it can occur that the value of the Asset that is to be sold decreases such that the requested net amount that one wants to receive in the OrderTrade is higher than the total value of that Asset in one’s Portfolio on the MarketDay. For this purpose, a TradeSafetyMargin is specified on the Label level. The TradeSafetyMargin represents the maximum percentage of the total value of an Asset in an Investor’s Portfolio that the Investor can sell on the same MarketDay without the corresponding OrderTrade being converted to a ~UnitBased~ “Sell All” OrderTrade.

Example: the TradeSafetyMargin for a Label is set to 90% (the default) and Investor X has 100 units of Asset 1 in their Portfolio, each with a value of 25 EUR. If Investor X wants to stay within the TradeSafetyMargin, they can sell Asset 1 for a net amount of at most (25 100 90% = ) 2.250 EUR. If Investor X wants to sell Asset 1 for a net amount of more than 2.250, the OrderTrade will automatically be converted to a ~UnitBased~ “Sell All” OrderTrade. In this OrderTrade, all 100 units of Asset 1 will be sold to increase the probability that Investor X will receive at least the desired amount of proceeds after execution of the corresponding Order.

PeriodicalSell (Contract)

Definition

If a User wants to periodically sell one or multiple Assets based on a certain recurrence pattern, a PeriodicalSell (Contract) can be created. If the ~AssetId~ property of a PeriodicalSell is null, this means a periodical ~ProRata~ Sell Order will be performed.

Relevant endpoints

• GET /PeriodicalSellContracts/{labelId}
• GET /PeriodicalSellContractGetById/{labelId}/{periodicalSellContractId}
• POST /PeriodicalSellContractAdd
• PUT /PeriodicalSellContractUpdate

OrderCorrection

Definition

After an incorrectly executed Order has been discovered, an OrderCorrection might need to be created to achieve the correct desired result of the original Order. An OrderCorrection is entered with an execution date that is in the past and is processed immediately. After an OrderCorrection has been processed, the total number of Assets on the Label level will not match the total number of Assets on the InvestorAccount level anymore. This difference will need to be corrected by placing ~CorrectionTrades~ for the next MarketDay. This correction will result in either a profit or loss on behalf of the Label. It is very possible for an OrderReversal to be combined with an OrderCorrection. The resulting ~CorrectionTrades~ can then be created to correct for both the operations at the same time.

Relevant endpoints

POST /OrderCorrectionAdd

OrderReversal

Definition

• Sometimes, all of the executed and reserved JournalEntries related to an Order need to be reversed. This can happen if an Order has been incorrectly entered into GiroPro, for example. These JournalEntries will then get an OrderTradeState of ‘Reversed’ and their ‘Hidden’ property will be set to ‘true’. Additionally, any SEPARecords that are the result of this Order also need to be reversed. This means that SEPARecords that have not yet been paid out need to be cancelled. For SEPARecords that have already been paid out, the Label might need to undertake certain actions themselves.
• After an OrderReversal has been processed, the total number of Assets on the Label level will not match the total number of Assets on the InvestorAccount level anymore. This difference will need to be corrected by placing ~CorrectionTrades~ for the next MarketDay. This correction will result in either a profit or loss on behalf of the Label.

Relevant endpoints

PUT /OrderReverse