Placing a nominal buy order

To place a nominal buy order, send

POST /orders

Example request

{
  "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9",
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "cash_amount": "1000",
  "currency": "EUR",
  "side": "BUY",
  "instrument_id": "US0378331005",
  "instrument_id_type": "ISIN",
  "order_type": "MARKET",
  "user_instrument_fit_acknowledgement": true,
  "limit_price": "",
  "stop_price": "",
  "fee_configuration": [
    {
      "cash_amount": "0.90",
      "currency": "EUR",
      "type": "TRANSACTION_FEE_BUY",
      "charge_method": "CHARGED_BY_CLIENT",
      "value_type": "ABSOLUTE"
    }
  ]
}

Payload

For the nominal buy order call, you need to provide the following attributes in the request payload. Any other required order data is populated by Upvest.

Parameter
Required
Description
cash_amountRequiredSpecify the cash amount. You can omit the share quantity (vice versa for a unit order), “BUY”` as order side
currencyRequiredSince each account group will have the cash balance for a specific currency, the currency for the order should be supported by that account group.
instrument_idRequiredSpecify the specific ISIN you want to trade in.
instrument_id_typeRequiredSpecify ISIN as instrument ID type.
NOTE: Soon we will also offer UUIDs so that the instrument id type gives you the freedom to interact with our API using UUIDs or ISINs depending on your needs and whatever is easiest for you.
client_referenceOptional*You can also provide your own generated order ID. This, for example, allows you to map orders back to your end-users in an easy manner.
NOTE: It does not have to be your order ID, it can be anything that you deem relevant, i.e. there is no guarantee that this value is unique.
user_instrument_fit_acknowledgementOptionalMust be set to true if the user has proven to you a non-instrument fit, but has accepted the related risks of which you have informed them. In all other cases it should be false.
NOTE: The absence of it will be equal to false. Consequently, Upvest is only interested in the outcome and needs to be able to prove whether an instrument fit check has been performed or not.
order_typeRequiredThe Investment API is designed to support MARKET, LIMIT, and STOP (Market) orders.
NOTE: LIMIT and STOP orders can only be placed as full unit orders, i.e. you can only Buy/Sell 1, 2, 3 shares of an instrument.
limit_priceConditionalMust be specified for LIMIT orders. The order is to be executed at the specified price (or better).
stop_priceConditionalMust be specified for STOP orders. The trigger price at which the order is automatically placed as a market order. .
NOTE: Placing a Stop Buy order with a stop_price below the current market price will result in an order cancellation because the market price might be more than the available cash amount on the account.
expiry_dateOptionalFor LIMIT and STOP orders it is the validity of order as the last day the order can trade (default is good-until-cancelled in case of absence of this field).
fee_configurationOptionalFee configuration with the following settings:
- cash_amount
- charge_method: Indicates whether the fee will be charged by the client or by other methods.
- currency
- type: Possible values for the fee type are TRANSACTION_FEE_BUY OR TRANSACTION_FEE_SELL
- value_type: The value must be ABSOLUTE

Response

After a successful order request, the sample response for the above will look as follows:

Example response

{
  "id": "eb5ba93f-5dfe-4bf1-8571-4da0caacc80c",
  "created_at": "2021-07-21T14:10:00.00Z",
  "updated_at": "2021-07-21T14:10:00.00Z",
  "user_id": "2dedfeb0-58cd-44f2-ae08-0e41fe0413d9",
  "account_id": "debf2026-f2da-4ff0-bb84-92e45babb1e3",
  "cash_amount": "1000",
  "currency": "EUR",
  "side": "BUY",
  "instrument_id": "US0378331005",
  "instrument_id_type": "ISIN",
  "order_type": "MARKET",
  "quantity": "0",
  "user_instrument_fit_acknowledgement": true,
  "limit_price": "",
  "stop_price": "",
  "status": "NEW",
  "fee": "0.0",
  "executions": [],
  "client_reference": "",
  "initiation_flow": "API",
  "fee_configuration": [
    {
      "cash_amount": "0.90",
      "charge_method": "CHARGED_BY_CLIENT",
      "currency": "EUR",
      "type": "TRANSACTION_FEE_BUY",
      "value_type": "ABSOLUTE"
    }
  ]
}
WARNING

Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.

Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.


State transition

Once all relevant order checks have been passed, the order transitions from NEW to the PROCESSING status and you will receive a webhook for an order event. At this point, the order can no longer be cancelled via the Investment API.

In addition to the status field, you will also see the initiation_flow used during order creation. The different values will give you insight into what triggered the order:

INFO

The values you can see depend on whether a certain feature is activated for you (such as Portfolio and Reinvestment functionality).


ParameterDescription
APIThe order was created via the POST /orders endpoint.
PORTFOLIOAn order is a result of a portfolio order placed via the POST /portfolios/orders endpoint.
PORTFOLIO_REBALANCINGAn order as a result of rebalancing to achieve the target weight of a given portfolio.
SELL_TO_COVER_FEESA sell order as a result of selling a position to collect fees from end users.
SELL_TO_COVER_TAXESA sell order as a result of selling a position to take in pre-payment income taxes, i.e. 'Vorabpauschale', from end users (only applicable to ETFs and mutual funds).
CASH_DIVIDEND_REINVESTMENTAn order as a result of automatically reinvested cash dividends.

After the checks the order gets executed at our trading partner and you will receive an order execution FILLED webhook for each execution, followed by an order FILLED webhook once the order is completely filled, including the amount of fees charged (if applicable). This means that executions will contain all order executions associated with this order.

Additionally, taxes get incurred with "type": "TOTAL" for buy orders where financial transaction taxes apply. This means that cash_amount + taxes.amount is deducted from the cash balance. You will also be able to see the total amount paid for such orders in the cash balance update event. For taxes incurred on sell orders see Placing a unit sell order.


Next steps

Was this page helpful?