# Placing a nominal buy order

To place a nominal buy order, send

**POST** [`/orders`](/api/orders/place_order)

**Example**

Example request

```json
{
  "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"
    }
  ]
}
```

Example response

```json
{
  "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",
      "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 | Description |
|  --- | --- |
| `cash_amount` | **Required**:Specify the cash amount. You can omit the share quantity (vice versa for a unit order), “BUY”` as order side |
| `currency` | **Required**: Since each account group will have the cash balance for a specific currency, the `currency` for the order should be supported by that account group (for example, EUR or GBP). |
| `instrument_id` | **Required**: Specify the specific ISIN you want to trade in. |
| `instrument_id_type` | **Required**: The type of the ID used in the request. **Example**: `ISIN` |
| `client_reference` | **Optional**:  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. 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_acknowledgement` | **Optional**: `true`: This check has been carried out. If this field is empty, i.e. has not been performed, Upvest would reject the order.**NOTE**: Please note that Upvest only takes into account whether the check has been performed or not. If the user has provided you with evidence of non-instrument suitability, but has accepted the associated risks that you have informed them about, we will accept the order. |
| `order_type` | **Required**: The 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_price` | **Conditional**: Must be specified for `LIMIT` orders. The order is to be executed at the specified price (or better). |
| `stop_price` | **Conditional**: Must 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_date` | **Optional**: For `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). When `expiry_date` is empty, we submit the order with the expiry set to 359 days. **NOTE**: When submitting an order with `expiry_date` above 359 days, the order may result in trade rejections at the exchange. |
| `fee_configuration` | **Optional**:  Fee 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` |


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

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](/api_errors) of the response to your requests and handle failure cases appropriately.

## Initiation flow - state transition

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 (such as **Portfolio** and **Reinvestment** functionality).

| Parameter | Description |
|  --- | --- |
| `API` | The order was created via the `POST` `/orders` endpoint. |
| `PORTFOLIO` | An order is a result of a portfolio order placed via the `POST` `/portfolios/orders` endpoint. |
| `PORTFOLIO_REBALANCING` | An order as a result of rebalancing to achieve the target weight of a given portfolio. |
| `SELL_TO_COVER_FEES` | A sell order as a result of selling a position to collect fees from end users. |
| `SELL_TO_COVER_TAXES` | A 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_REINVESTMENT` | An 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.

## Taxes

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](/products/omnibus/guides/orders/unit_sell_orders/unit_sell_order_placing).

## Webhook

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.