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": ""
}
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.
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"
}
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:
The values you can see depend on whether a certain feature is activated for you (i.e Portfolio, Fee, and Reinvestment functionality).
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.
Was this page helpful?