# 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](https://docs.upvest.co/products/tol/guides/orders) / [BYOL](https://docs.upvest.co/products/byol/guides/orders) / [Omnibus](https://docs.upvest.co/products/omnibus/guides/orders)) for order lifecycle details.

Endpoint: POST /orders
Version: 1.148.0
Security: oauth-client-credentials

## Security:

  - `oauth-client-credentials` (unknown)
    oauth2 scopes: orders:admin

## Header parameters:

  - `idempotency-key` (string, required)
    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

  - `upvest-client-id` (string, required)
    Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).

  - `Authorization` (string, required)
    Bearer (access) token from the OAuth flow with correct scopes.
https://datatracker.ietf.org/doc/html/rfc6750

  - `signature` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

  - `signature-input` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

  - `upvest-api-version` (string)
    Upvest API version (Note: Do not include quotation marks)

## Request fields (application/json):

  - `user_id` (string)
    The ID of the user. Either user ID or business ID must be specified.

  - `business_id` (string)
    The ID of the business. Either user ID or business ID must be specified.

  - `account_id` (string, required)
    The ID of the account that owns the order

  - `cash_amount` (string)
    Cash amount for a nominal order, not required if a share quantity is specified.

  - `currency` (string)
    The currency for the order.
    Enum: "EUR", "GBP", "USD"

  - `side` (string, required)
    Side of the order.
* BUY — purchases the specified instrument.
* SELL — disposes of the specified instrument.
    Enum: "BUY", "SELL"

  - `instrument_id` (string, required)
    International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).

  - `instrument_id_type` (string, required)
    The type of the ID used in the request.
* ISIN -
    Enum: "ISIN"

  - `order_type` (string)
    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.
    Enum: "MARKET", "LIMIT", "STOP"

  - `quantity` (string)
    Quantity of securities for the order. Only required if the cash amount is not specified.

  - `user_instrument_fit_acknowledgement` (boolean)
    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.

  - `limit_price` (string)
    The limit price for orders of the type 'limit'.

  - `stop_price` (string)
    The stop price for orders of the type 'stop'.

  - `expiry_date` (string)
    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](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days

  - `client_reference` (string)
    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` (string)
    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.
    Enum: "STRAIGHT_THROUGH", "BLOCK"

  - `fee_configuration` (array)
    fee configuration

  - `fee_configuration.type` (string, required)
    Fee type
* TRANSACTION_FEE_BUY -
* TRANSACTION_FEE_SELL -
    Enum: "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL"

  - `fee_configuration.value_type` (string, required)
    The value type must be “ABSOLUTE”.

  - `fee_configuration.charge_method` (string, required)
    Indicates whether the fee will be charged by client or by other methods.
* CHARGED_BY_CLIENT -
* COLLECTED_BY_UPVEST -
    Enum: "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST"

  - `fee_configuration.cash_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `fee_configuration.currency` (string, required)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* EUR - Euro
* GBP - British Pound
* USD - US Dollar
    Enum: "EUR", "GBP", "USD"

  - `fee_configuration.transaction_fee_model_id` (string, required)
    The ID of the transaction fee model.

  - `decision_maker_id` (string)
    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)

## Request examples:

  - `Nominal Buy Order Request` (unknown)

  - `Nominal Buy Order Request with fee configuration` (unknown)

  - `Nominal Buy Order Request with fee model` (unknown)

  - `Unit Sell Order Request` (unknown)

  - `Unit Sell Order Request with fee configuration` (unknown)

## Response 202:

  - `202` (unknown)
    The request for the order creation has been accepted for processing.

## Response 202 fields (application/json):

  - `id` (string, required)
    Unique identifier for an order. Universally Unique Identifier (UUID).

  - `created_at` (string, required)
    Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `updated_at` (string, required)
    Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `user_id` (string)
    The ID of the user. Either user ID or business ID must be specified.

  - `business_id` (string)
    The ID of the business. Either user ID or business ID must be specified.

  - `account_id` (string, required)
    The ID of the account that owns the order

  - `cash_amount` (string, required)
    Cash amount for a nominal order, not required if a share quantity is specified.

  - `currency` (string, required)
    The currency for the order.
    Enum: "EUR", "GBP", "USD"

  - `side` (string, required)
    Side of the order.
* BUY — purchases the specified instrument.
* SELL — disposes of the specified instrument.
    Enum: "BUY", "SELL"

  - `instrument_id` (string, required)
    International securities identification number defined by [ISO 6166](https://en.wikipedia.org/wiki/International_Securities_Identification_Number).

  - `instrument_id_type` (string, required)
    The type of the ID used in the request.
* ISIN -
    Enum: "ISIN"

  - `order_type` (string, required)
    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.
    Enum: "MARKET", "LIMIT", "STOP"

  - `quantity` (string, required)
    Quantity of securities for the order. Only required if the cash amount is not specified.

  - `user_instrument_fit_acknowledgement` (boolean)
    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.

  - `limit_price` (string)
    The limit price for orders of the type 'limit'.

  - `stop_price` (string)
    The stop price for orders of the type 'stop'.

  - `expiry_date` (string)
    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](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339. The default value is order creation date + 359 days

  - `status` (string, required)
    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.
    Enum: "NEW", "PROCESSING", "FILLED", "CANCELLED"

  - `fee` (string, required)
    A positive decimal amount, as a string.

  - `cancellation_reason` (string)
    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.
    Enum: "CANCELLED_BY_CLIENT", "CANCELLED_BY_UPVEST_OPERATIONS", "CANCELLED_BY_TRADING_PARTNER", "CANCELLED_BY_UPVEST_PLATFORM"

  - `initiation_flow` (string, required)
    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.
    Enum: "API", "PORTFOLIO", "CASH_DIVIDEND_REINVESTMENT", "PORTFOLIO_REBALANCING", "SELL_TO_COVER_FEES", "SELL_TO_COVER_TAXES", "ACCOUNT_LIQUIDATION", "UPVEST_OPERATIONS", "SAVINGS_PLAN", "CLIENT_OPERATIONS"

  - `execution_flow` (string)
    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.
    Enum: "STRAIGHT_THROUGH", "BLOCK"

  - `executions` (array, required)
    Order executions associated with this order

  - `executions.id` (string, required)

  - `executions.cash_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `executions.share_quantity` (string, required)
    A positive decimal amount, as a string.

  - `executions.price` (string, required)
    Price of an instrument for a trade execution provided as a decimal string.

  - `executions.transaction_time` (string, required)
    Timestamp of when the trade was executed at the market. [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format.

  - `executions.taxes` (array, required)
    Taxes deducted as part of this execution.

  - `executions.taxes.type` (string, required)
    Tax type
* TOTAL -
    Enum: "TOTAL"

  - `executions.taxes.amount` (string, required)
    A positive decimal amount, as a string.

  - `executions.order_id` (string, required)
    Unique identifier for an order. Universally Unique Identifier (UUID).

  - `executions.status` (string, required)
    Status of the execution.
* FILLED — the execution has been filled.
* SETTLED — the execution has settled and securities and cash have been exchanged.
* CANCELLED — the execution was cancelled before settlement.
    Enum: "FILLED", "SETTLED", "CANCELLED"

  - `executions.side` (string, required)
    Side of the execution.
* BUY — a buy execution.
* SELL — a sell execution.
    Enum: "BUY", "SELL"

  - `executions.currency` (string, required)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* EUR - Euro
* GBP - British Pound
* USD - US Dollar
    Enum: "EUR", "GBP", "USD"

  - `executions.settlement_date` (string)
    Order execution settlement date in the YYYY-MM-DD format. [RFC 3339, section 5.6](https://json-schema.org/draft/2020-12/json-schema-validation.html#RFC3339) RFC 3339

  - `executions.venue_id` (string, required)
    The ID of the venue

  - `client_reference` (string)
    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.

  - `fee_configuration` (array)
    Fee configuration applied to this order. Determines how the order fee is calculated.

  - `fee_configuration.type` (string, required)
    Fee type
* TRANSACTION_FEE_BUY -
* TRANSACTION_FEE_SELL -
    Enum: "TRANSACTION_FEE_BUY", "TRANSACTION_FEE_SELL"

  - `fee_configuration.value_type` (string, required)
    The value type must be “ABSOLUTE”.

  - `fee_configuration.charge_method` (string, required)
    Indicates whether the fee will be charged by client or by other methods.
* CHARGED_BY_CLIENT -
* COLLECTED_BY_UPVEST -
    Enum: "CHARGED_BY_CLIENT", "COLLECTED_BY_UPVEST"

  - `fee_configuration.cash_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `fee_configuration.currency` (string, required)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* EUR - Euro
* GBP - British Pound
* USD - US Dollar
    Enum: "EUR", "GBP", "USD"

  - `fee_configuration.transaction_fee_model_id` (string, required)
    The ID of the transaction fee model.

  - `decision_maker_id` (string)
    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 202 headers (application/json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 400:

  - `400` (unknown)
    Bad Request. The incoming request had a malformed parameter/object.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 400 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 401:

  - `401` (unknown)
    Unauthorized. The caller has not been authenticated.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 401 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 403:

  - `403` (unknown)
    Forbidden. The caller has been authenticated but is not allowed to take the requested action.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 403 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 406:

  - `406` (unknown)
    Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 406 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 422:

  - `422` (unknown)
    Unprocessable Entity. The syntax of request is correct but server can't process it due a semantic error.

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 422 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 429:

  - `429` (unknown)
    Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 429 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 500:

  - `500` (unknown)
    Internal Server Error. The service encountered an unexpected error.

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 500 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 503:

  - `503` (unknown)
    Service Unavailable. The service handling for this request cannot be reached at this time.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 503 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 504:

  - `504` (unknown)
    Gateway Timeout. The service gateway has reached its internal timeout.

## Response 504 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 504 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 202 examples:

  - `Nominal Buy Order Response` (unknown)

  - `Nominal Buy Order Response with fee configuration` (unknown)

  - `Nominal Buy Order Response with fee model` (unknown)

  - `Nominal Buy Order Response with Executions` (unknown)

  - `Unit Sell Order Response` (unknown)

  - `Unit Sell Order Response with fee configuration` (unknown)

  - `Unit Sell Order Response with fee model` (unknown)

  - `Unit Sell Order Response with Executions` (unknown)