Place Order V3 | Upstox Developer API

Place Order V3 Sandbox Enabled

API to place an order to the exchange. The instrument_token required for the stock or contracts should be obtained from the BOD instruments.

Upon successfully placing the order with the exchange, a unique order_id is provided in the success response, which can be utilized for order modification or cancellation. If you intend to place an order outside of market hours, the 'is_amo' (After Market Order) should be set to 'true'. You can assign a tag(unique identifier) to your order, allowing you to retrieve orders associated with that tag using the Order History API.

Featuring an auto-slicing capability to break down large orders into smaller sizes bases on the freeze quantity of the instrument. You can enable or disable this feature by setting the slice flag in your order. For more details, please refer to the Auto Slicing

This API also includes latency information in the meta data object of the response, providing insight into the time Upstox took to process your request.

Request

curl --location 'https://api-hft.upstox.com/v3/order/place' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}' \
--data '{
  "quantity": 4000,
  "product": "D",
  "validity": "DAY",
  "price": 0,
  "tag": "string",
  "instrument_token": "NSE_FO|43919",
  "order_type": "MARKET",
  "transaction_type": "BUY",
  "disclosed_quantity": 0,
  "trigger_price": 0,
  "is_amo": false,
  "slice": true
}'

For additional samples in various languages, please refer to the Sample code section on this page.

Request Body

Name	Required	Type	Description
quantity	true	integer (int32)	Quantity with which the order is to be placed. For commodity - number of lots is accepted. For other Futures & Options and equities - number of units is accepted in multiples of the tick size.
product	true	string	Signifies if the order was either Intraday or Delivery. Possible values: `I`, `D`, `MTF`.
validity	true	string	It can be one of the following - DAY(default), IOC. Possible values: `DAY`, `IOC`.
price	true	number (float)	Price at which the order will be placed
tag	false	string	Tag for a particular order
instrument_token	true	string	Key of the instrument. For the regex pattern applicable to this field, see the Field Pattern Appendix.
order_type	true	string	Type of order. It can be one of the following MARKET refers to market order LIMIT refers to Limit Order SL refers to Stop Loss Limit SL-M refers to Stop Loss Market. Possible values: `MARKET`, `LIMIT`, `SL`, `SL-M`.
transaction_type	true	string	Indicates whether its a buy or sell order. Possible values: `BUY`, `SELL`.
disclosed_quantity	true	integer (int32)	The quantity that should be disclosed in the market depth
trigger_price	true	number (float)	If the order is a stop loss order then the trigger price to be set is mentioned here
is_amo	true	boolean	Signifies if the order is an After Market Order
slice	false	boolean	When `true`, the number of orders is calculated based on the freeze quantity assigned for the instrument by the exchange. This helps automatically split the order into smaller parts in accordance with exchange rules, preventing rejection due to exceeding the allowed quantity. The default value is `false`. For a detailed explanation, please check the Auto Slicing section. When `slicing` is applied, we calculate the total number of resulting orders. The total number of orders generated by the slice, must not exceed the maximum order count specified here.

Responses

Response Body

{
    "status": "success",
    "data": {
        "order_ids": [
            "1644490272000",
            "1644490272001",
            "1644490272003"
        ]
    },
    "metadata": {
        "latency": 30
    }
}

Name	Type	Description
status	string	A string indicating the outcome of the request. Typically `success` for successful operations.
data	object	Response data for place order request.
data.order_ids	array	List of reference order IDs associated with successful order placed.
metadata	object	Order metadata associated with successful order placed.
metadata.latency	integer	The overall time taken by API platform to process the order request, measured in milliseconds.

Error codes

Error code	Description
UDAPI1026	Instrument key is required - You need to provide the instrument key for this operation.
UDAPI1004	Valid order type is required - Please ensure to provide a recognized order type.
UDAPI1056	The 'order_type' is invalid - The specified order type isn't acceptable.
UDAPI1057	The 'transaction_type' is invalid - The given transaction type is not valid.
UDAPI1006	Product is required - You must specify the product in your request.
UDAPI1054	The 'product' is invalid - The provided product value doesn't match any accepted values.
UDAPI1007	Validity is required - You need to provide the duration the order will remain in effect.
UDAPI1055	The 'validity' is invalid - The specified order validity isn't recognized.
UDAPI1008	Price is required - Please specify the price in your request.
UDAPI100049	Access to this API has been restricted for your account. Please use 'Uplink Business' to place/modify/cancel the order. - Use 'Uplink Business' for order operations.
UDAPI1052	The order 'quantity' cannot be zero - You cannot set the order quantity to zero.
UDAPI1040	Price not required - You shouldn't specify a price for this type of order.
UDAPI1043	The 'price' is required - A valid price value needs to be provided for this order type.
UDAPI1041	The 'price' and 'trigger_price' both are required - Ensure to specify both price values in your request.
UDAPI1042	Only 'trigger_price' is required - Only the trigger price needs to be provided, not the regular price.
UDAPI1037	Trigger price should be less than limit price - Ensure your trigger price is set below the limit price.
UDAPI1038	Trigger price should be greater than limit price - The trigger price should exceed the limit price value.
UDAPI100011	Invalid Instrument key - The instrument key you provided doesn't match any recognized keys.
UDAPI100039	AMO orders cannot be placed during the market hours - After Market Order (AMO) is not valid during active market sessions.
UDAPI100074	The Place order API is accessible from 5:30 AM to 12:00 AM IST daily - Thrown when an Place Order API is called between midnight and 5:30 AM in the morning.
UDAPI1118	Maximum order limit exceeded - When slicing enabled, the number of orders in this request exceeds the maximum allowed count. Requests with more than the permissible limit of orders will be rejected immediately.
UDAPI1119	tag length exceeds limit - The length of the `tag` exceeds the permitted limit of 40 characters. Ensure each `tag` is within the defined limit.

Auto Slicing

Exchanges enforce a limitation on the maximum quantity that can be placed for any scrip, known as the freeze quantity. If an order exceeds this freeze quantity, it will be rejected by the exchange. To simplify the process and prevent such rejections, we automatically slice the order into smaller parts based on the freeze quantity defined by the exchange when necessary.

How to Enable Slicing

To enable this feature, include the slice field in your request payload with the value set to true. Let's walk through a practical example:

Suppose you want to place an order for SCRIP1 with a total quantity of 10,100, and the freeze quantity defined by the exchange is 1,000. If you send the slice field as false, the entire order is submitted to the exchange, which will reject it due to exceeding the allowed quantity. However, if you pass true as the value for the slice field, we automatically split the order into 11 smaller orders: 10 orders of 1,000 units each, and 1 order of 100 units. This ensures that all orders are accepted and processed by the exchange.

Sample Code

Place an order with slicing enabled

curl --location 'https://api-hft.upstox.com/v3/order/place' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}' \
--data '{
  "quantity": 4000,
  "product": "D",
  "validity": "DAY",
  "price": 0,
  "tag": "string",
  "instrument_token": "NSE_FO|43919",
  "order_type": "MARKET",
  "transaction_type": "BUY",
  "disclosed_quantity": 0,
  "trigger_price": 0,
  "is_amo": false,
  "slice": true
}'

import requests

url = 'https://api-hft.upstox.com/v3/order/place'
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer {your_access_token}',
}

data = {
    'quantity': 4000,
    'product': 'D',
    'validity': 'DAY',
    'price': 0,
    'tag': 'string',
    'instrument_token': 'NSE_FO|43919',
    'order_type': 'MARKET',
    'transaction_type': 'BUY',
    'disclosed_quantity': 0,
    'trigger_price': 0,
    'is_amo': False,
    'slice': True
}

try:
    # Send the POST request
    response = requests.post(url, json=data, headers=headers)

    # Print the response status code and body
    print('Response Code:', response.status_code)
    print('Response Body:', response.json())

except Exception as e:
    # Handle exceptions
    print('Error:', str(e))

const axios = require('axios');

const url = 'https://api-hft.upstox.com/v3/order/place';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {your_access_token}',
};

const data = {
  quantity: 4000,
  product: 'D',
  validity: 'DAY',
  price: 0,
  tag: 'string',
  instrument_token: 'NSE_FO|43919',
  order_type: 'MARKET',
  transaction_type: 'BUY',
  disclosed_quantity: 0,
  trigger_price: 0,
  is_amo: false,
  slice: true
};

axios.post(url, data, { headers })
  .then(response => {
    console.log('Response:', response.data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;


public class Main {

    public static void main(String[] args) {
        String url = "https://api-hft.upstox.com/v3/order/place";
        String token = "Bearer {your_access_token}";

        // Set up the request body
        String requestBody = "{"
                + "\"quantity\": 4000,"
                + "\"product\": \"D\","
                + "\"validity\": \"DAY\","
                + "\"price\": 0,"
                + "\"tag\": \"string\","
                + "\"instrument_token\": \"NSE_FO|43919\","
                + "\"order_type\": \"MARKET\","
                + "\"transaction_type\": \"BUY\","
                + "\"disclosed_quantity\": 0,"
                + "\"trigger_price\": 0,"
                + "\"is_amo\": false,"
                + "\"slice\": true"
                + "}";

        // Create the HttpClient
        HttpClient httpClient = HttpClient.newHttpClient();

        // Create the HttpRequest
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .header("Authorization", token)
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        try {
            // Send the request and retrieve the response
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            // Print the response status code and body
            System.out.println("Response Code: " + response.statusCode());
            System.out.println("Response Body: " + response.body());

        } catch (Exception e) {
            // Handle exceptions
            e.printStackTrace();
        }
    }
}

<?php

$url = 'https://api-hft.upstox.com/v3/order/place';
$headers = [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {your_access_token}',
];

$data = [
    'quantity' => 4000,
    'product' => 'D',
    'validity' => 'DAY',
    'price' => 0,
    'tag' => 'string',
    'instrument_token' => 'NSE_FO|43919',
    'order_type' => 'MARKET',
    'transaction_type' => 'BUY',
    'disclosed_quantity' => 0,
    'trigger_price' => 0,
    'is_amo' => false,
    'slice' => true,
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

if ($response === false) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo 'Response: ' . $response;
}

curl_close($ch);
?>

import upstox_client
from upstox_client.rest import ApiException
configuration = upstox_client.Configuration()
configuration.access_token = '{your_access_token}'
api_instance = upstox_client.OrderApiV3(upstox_client.ApiClient(configuration))
body = upstox_client.PlaceOrderV3Request(quantity=4000, product="D", validity="DAY", 
    price=0, tag="string", instrument_token="NSE_FO|43919", 
    order_type="MARKET", transaction_type="BUY", disclosed_quantity=0, 
    trigger_price=0.0, is_amo=False, slice=True)

try:
    api_response = api_instance.place_order(body)
    print(api_response)
except ApiException as e:
    print("Exception when calling OrderApiV3->place_order: %s\n" % e)

let UpstoxClient = require('upstox-js-sdk');
let defaultClient = UpstoxClient.ApiClient.instance;
var OAUTH2 = defaultClient.authentications['OAUTH2'];
OAUTH2.accessToken = "{your_access_token}";

let apiInstance = new UpstoxClient.OrderApiV3();
let body = new UpstoxClient.PlaceOrderV3Request(4000, 
    UpstoxClient.PlaceOrderV3Request.ProductEnum.D,
    UpstoxClient.PlaceOrderV3Request.ValidityEnum.DAY, 
    0, "NSE_FO|43919",
    UpstoxClient.PlaceOrderV3Request.OrderTypeEnum.MARKET,
    UpstoxClient.PlaceOrderV3Request.TransactionTypeEnum.BUY,
    0, 0, false);
let opt = {"slice": true}

apiInstance.placeOrder(body, opt, (error, data, response) => {
  if (error) {
    console.error(error.response.text);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
});

import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.OrderApiV3;
import com.upstox.api.PlaceOrderV3Request;
import com.upstox.api.PlaceOrderV3Response;

public class Main {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setAccessToken("{your_access_token}");

        OrderApiV3 apiInstance = new OrderApiV3();
        PlaceOrderV3Request body = new PlaceOrderV3Request();
        body.setQuantity(4000);
        body.setProduct(PlaceOrderV3Request.ProductEnum.D);
        body.setValidity(PlaceOrderV3Request.ValidityEnum.DAY);
        body.setPrice(0F);
        body.setTag("string");
        body.setInstrumentToken("NSE_FO|43919");
        body.orderType(PlaceOrderV3Request.OrderTypeEnum.MARKET);
        body.setTransactionType(PlaceOrderV3Request.TransactionTypeEnum.BUY);
        body.setDisclosedQuantity(0);
        body.setTriggerPrice(0F);
        body.setIsAmo(false);
        body.setSlice(true);

        try {
            PlaceOrderV3Response result = apiInstance.placeOrder(body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling OrderApiV3->placeOrder: " + e.getMessage());
        }
    }
}

Place an order with slicing disabled

curl --location 'https://api-hft.upstox.com/v3/order/place' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}' \
--data '{
  "quantity": 25,
  "product": "D",
  "validity": "DAY",
  "price": 0,
  "tag": "string",
  "instrument_token": "NSE_FO|43919",
  "order_type": "MARKET",
  "transaction_type": "BUY",
  "disclosed_quantity": 0,
  "trigger_price": 0,
  "is_amo": false,
  "slice": false
}'

import requests

url = 'https://api-hft.upstox.com/v3/order/place'
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer {your_access_token}',
}

data = {
    'quantity': 25,
    'product': 'D',
    'validity': 'DAY',
    'price': 0,
    'tag': 'string',
    'instrument_token': 'NSE_FO|43919',
    'order_type': 'MARKET',
    'transaction_type': 'BUY',
    'disclosed_quantity': 0,
    'trigger_price': 0,
    'is_amo': False,
    'slice': False
}

try:
    # Send the POST request
    response = requests.post(url, json=data, headers=headers)

    # Print the response status code and body
    print('Response Code:', response.status_code)
    print('Response Body:', response.json())

except Exception as e:
    # Handle exceptions
    print('Error:', str(e))

const axios = require('axios');

const url = 'https://api-hft.upstox.com/v3/order/place';
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {your_access_token}',
};

const data = {
  quantity: 25,
  product: 'D',
  validity: 'DAY',
  price: 0,
  tag: 'string',
  instrument_token: 'NSE_FO|43919',
  order_type: 'MARKET',
  transaction_type: 'BUY',
  disclosed_quantity: 0,
  trigger_price: 0,
  is_amo: false,
  slice: false
};

axios.post(url, data, { headers })
  .then(response => {
    console.log('Response:', response.data);
  })
  .catch(error => {
    console.error('Error:', error.message);
  });

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;


public class Main {

    public static void main(String[] args) {
        String url = "https://api-hft.upstox.com/v3/order/place";
        String token = "Bearer {your_access_token}";

        // Set up the request body
        String requestBody = "{"
                + "\"quantity\": 25,"
                + "\"product\": \"D\","
                + "\"validity\": \"DAY\","
                + "\"price\": 0,"
                + "\"tag\": \"string\","
                + "\"instrument_token\": \"NSE_FO|43919\","
                + "\"order_type\": \"MARKET\","
                + "\"transaction_type\": \"BUY\","
                + "\"disclosed_quantity\": 0,"
                + "\"trigger_price\": 0,"
                + "\"is_amo\": false,"
                + "\"slice\": false"
                + "}";

        // Create the HttpClient
        HttpClient httpClient = HttpClient.newHttpClient();

        // Create the HttpRequest
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .header("Authorization", token)
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        try {
            // Send the request and retrieve the response
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            // Print the response status code and body
            System.out.println("Response Code: " + response.statusCode());
            System.out.println("Response Body: " + response.body());

        } catch (Exception e) {
            // Handle exceptions
            e.printStackTrace();
        }
    }
}

<?php

$url = 'https://api-hft.upstox.com/v3/order/place';
$headers = [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {your_access_token}',
];

$data = [
    'quantity' => 25,
    'product' => 'D',
    'validity' => 'DAY',
    'price' => 0,
    'tag' => 'string',
    'instrument_token' => 'NSE_FO|43919',
    'order_type' => 'MARKET',
    'transaction_type' => 'BUY',
    'disclosed_quantity' => 0,
    'trigger_price' => 0,
    'is_amo' => false,
    'slice' => false,
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

if ($response === false) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo 'Response: ' . $response;
}

curl_close($ch);
?>

import upstox_client
from upstox_client.rest import ApiException
configuration = upstox_client.Configuration()
configuration.access_token = '{your_access_token}'
api_instance = upstox_client.OrderApiV3(upstox_client.ApiClient(configuration))
body = upstox_client.PlaceOrderV3Request(quantity=75, product="D", validity="DAY", 
    price=0, tag="string", instrument_token="NSE_FO|43919", 
    order_type="MARKET", transaction_type="BUY", disclosed_quantity=0, 
    trigger_price=0.0, is_amo=False, slice=False)

try:
    api_response = api_instance.place_order(body)
    print(api_response)
except ApiException as e:
    print("Exception when calling OrderApiV3->place_order: %s\n" % e)

let UpstoxClient = require('upstox-js-sdk');
let defaultClient = UpstoxClient.ApiClient.instance;
var OAUTH2 = defaultClient.authentications['OAUTH2'];
OAUTH2.accessToken = "{your_access_token}";

let apiInstance = new UpstoxClient.OrderApiV3();
let body = new UpstoxClient.PlaceOrderV3Request(75, 
    UpstoxClient.PlaceOrderV3Request.ProductEnum.D,
    UpstoxClient.PlaceOrderV3Request.ValidityEnum.DAY, 
    0, "NSE_FO|43919",
    UpstoxClient.PlaceOrderV3Request.OrderTypeEnum.MARKET,
    UpstoxClient.PlaceOrderV3Request.TransactionTypeEnum.BUY,
    0, 0, false);
let opt = {"slice": false}

apiInstance.placeOrder(body, opt, (error, data, response) => {
  if (error) {
    console.error(error.response.text);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
});

import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.OrderApiV3;
import com.upstox.api.PlaceOrderV3Request;
import com.upstox.api.PlaceOrderV3Response;

public class Main {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setAccessToken("{your_access_token}");

        OrderApiV3 apiInstance = new OrderApiV3();
        PlaceOrderV3Request body = new PlaceOrderV3Request();
        body.setQuantity(75);
        body.setProduct(PlaceOrderV3Request.ProductEnum.D);
        body.setValidity(PlaceOrderV3Request.ValidityEnum.DAY);
        body.setPrice(0F);
        body.setTag("string");
        body.setInstrumentToken("NSE_FO|43919");
        body.orderType(PlaceOrderV3Request.OrderTypeEnum.MARKET);
        body.setTransactionType(PlaceOrderV3Request.TransactionTypeEnum.BUY);
        body.setDisclosedQuantity(0);
        body.setTriggerPrice(0F);
        body.setIsAmo(false);
        body.setSlice(false);

        try {
            PlaceOrderV3Response result = apiInstance.placeOrder(body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling OrderApiV3->placeOrder: " + e.getMessage());
        }
    }
}

Place Order V3 Sandbox Enabled​

Request​

Request Body​

Response Body​

Error codes​

Auto Slicing​

How to Enable Slicing​

Sample Code​

Place an order with slicing enabled​

Place an order with slicing disabled​