Place an order
Places a new order for an instrument. After the request is accepted, the order is processed asynchronously — use the returned id to poll for status or subscribe to order webhook events.
See the Orders guide (TOL / BYOL / Omnibus) for order lifecycle details.
Headers
A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed. https://docs.upvest.co/documentation/concepts/api_concepts/idempotency
Request body
The ID of the user. Either user ID or business ID must be specified.
The ID of the business. Either user ID or business ID must be specified.
The ID of the account that owns the order
Cash amount for a nominal order, not required if a share quantity is specified.
The currency for the order.
Side of the order.
- BUY — purchases the specified instrument.
- SELL — disposes of the specified instrument.
International securities identification number defined by ISO 6166.
The type of the ID used in the request.
- ISIN -
Type of the order.
- MARKET — executes immediately at the best available market price.
- LIMIT — executes only at or better than the specified limit_price.
- STOP — triggers when the market price reaches stop_price, then executes at the prevailing market price.
Quantity of securities for the order. Only required if the cash amount is not specified.
Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade.
The limit price for orders of the type 'limit'.
The stop price for orders of the type 'stop'.
The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. RFC 3339, section 5.6 RFC 3339. The default value is order creation date + 359 days
Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.
Execution flow for order processing. Defaults to STRAIGHT_THROUGH if not specified.
- STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.
- BLOCK — the order is bundled with other orders for block execution.
ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)
Response
The request for the order creation has been accepted for processing.
Unique identifier for an order. Universally Unique Identifier (UUID).
Date and time when the resource was created. RFC 3339-5, ISO8601 UTC
Date and time when the resource was last updated. RFC 3339-5, ISO8601 UTC
The ID of the user. Either user ID or business ID must be specified.
The ID of the business. Either user ID or business ID must be specified.
The ID of the account that owns the order
Cash amount for a nominal order, not required if a share quantity is specified.
The currency for the order.
Side of the order.
- BUY — purchases the specified instrument.
- SELL — disposes of the specified instrument.
International securities identification number defined by ISO 6166.
The type of the ID used in the request.
- ISIN -
Type of the order.
- MARKET — executes immediately at the best available market price.
- LIMIT — executes only at or better than the specified limit_price.
- STOP — triggers when the market price reaches stop_price, then executes at the prevailing market price.
Quantity of securities for the order. Only required if the cash amount is not specified.
Only applicable if the user has failed the instrument fit check for the instrument type being ordered. True if the user has acknowledged their willingness to trade.
The limit price for orders of the type 'limit'.
The stop price for orders of the type 'stop'.
The order expiration date (last day the order can trade) in the YYYY-MM-DD format. The expiry date can only be set for LIMIT and STOP orders. RFC 3339, section 5.6 RFC 3339. The default value is order creation date + 359 days
The execution status of the order.
- NEW — the order has been received and validated, awaiting routing.
- PROCESSING — the order is being routed for execution.
- FILLED — the order has been fully executed.
- CANCELLED — the order was cancelled before being fully executed.
Reason for order cancellation. Present only when status is CANCELLED.
- CANCELLED_BY_CLIENT — cancelled at the end user's or client's request via the API.
- CANCELLED_BY_UPVEST_OPERATIONS — cancelled by Upvest operations.
- CANCELLED_BY_TRADING_PARTNER — cancelled by the executing partner.
- CANCELLED_BY_UPVEST_PLATFORM — cancelled automatically by the Upvest platform.
Identifies what triggered the order.
- API — initiated directly via the client API.
- PORTFOLIO — initiated by a portfolio rebalancing flow.
- CASH_DIVIDEND_REINVESTMENT — initiated as part of dividend reinvestment.
- PORTFOLIO_REBALANCING — initiated by an automated rebalancing.
- SELL_TO_COVER_FEES — initiated automatically to cover outstanding fees.
- SELL_TO_COVER_TAXES — initiated automatically to cover tax obligations.
- ACCOUNT_LIQUIDATION — initiated as part of an account liquidation.
- UPVEST_OPERATIONS — initiated by Upvest operations.
- SAVINGS_PLAN — initiated by a savings plan execution.
- CLIENT_OPERATIONS — initiated by client operations.
Execution flow for order processing. Defaults to STRAIGHT_THROUGH if not specified.
- STRAIGHT_THROUGH — the order is routed and executed directly without manual intervention.
- BLOCK — the order is bundled with other orders for block execution.
Immutable reference to the API flow that initiated the order. For client initiated API flows, this is a client provided ID. For internal initiations, it is set to the ID of the related object.
ID of the user behind the decision to place an order. Required only if different from the user_id. (e.g. child account order placed by a guardian)
Changes
No recorded changes to this endpoint across all 7 revisions of this API.