POST/us/order/place
Place Order
API to place a market or limit order for a US stock. Get the instrument_key from the US instruments file.
Size an order in one of two ways:
- By quantity — send
quantityin shares. Fractional quantities (up to 9 decimal places) are allowed only for stocks withfractionable: true. - By amount — send
amountin USD (up to 2 decimal places). The order buys fractional shares, so it is allowed only for fractionable stocks.
Send exactly one of quantity or amount. A successful request returns an order_id, which you can use to cancel or track the order.
- The order value must be between $1 and $40,000, and the size cannot exceed 999,999. The value limits are checked upfront only when the value is fixed: for an amount order, or a limit order (quantity × price).
- Place Order allows 3 requests per second. See US Stocks rate limits.
- A
MARKETorder must not carry a price. Omitpriceor send0. - You don't need to flag an after-market order. Before placing an order, Upstox checks the US market status. An order placed while the status is anything other than
NORMAL_OPENis placed as an after-market order (AMO), andis_amoistruein the order book. - Session, funds and sell-quantity checks are done by the US broker. A failed check returns HTTP
400withUDAPI100500and the broker's reason in the error message.
US orders can't be modified. To change an open order, cancel it and place a new order.
Request
curl --location --request POST 'https://api.upstox.com/v2/us/order/place' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_access_token}' \
--data '{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1.5,
"price": 180.25,
"validity": "DAY",
"tag": "my-strategy"
}'
For samples in other languages, see the Sample Code section on this page.
Request Body
| Name | Required | Type | Description |
|---|---|---|---|
| instrument_key | Required | string | US instrument key from the US instruments file, for example US_EQ|AAPL. |
| transaction_type | Required | string | Possible values: BUY, SELL. |
| order_type | Required | string | Possible values: MARKET, LIMIT. |
| validity | Required | string | Possible value: DAY. |
| quantity | Optional | number | Number of shares, up to 9 decimal places. Fractions are allowed only for fractionable stocks. Send either quantity or amount. |
| amount | Optional | number | USD to invest, up to 2 decimal places. Allowed only for fractionable stocks. Send either quantity or amount. |
| price | Optional | number | Limit price in USD. Required for a LIMIT order and not allowed for a MARKET order. Up to 2 decimal places at or above $1, and up to 4 below $1. |
| tag | Optional | string | Free-form tag for the order, up to 40 characters. Pass the same tag to Get Order Book to list only these orders. |
To invest $25 in a fractionable stock, send "amount": 25 and omit quantity:
{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "MARKET",
"amount": 25,
"validity": "DAY"
}
Responses
- 200
- 4XX
Response Body
{
"status": "success",
"data": {
"order_id": "1a9ecf08-e5f8-475c-a7c0-9056826d4b18"
}
}
| Name | Type | Description |
|---|---|---|
| status | string | Outcome of the request. Typically success. |
| data | object | Response data for the place order request. |
| data.order_id | string | Unique order ID of the placed order. |
Error codes
| Error code | Description |
|---|---|
| UDAPI1026 | Instrument key is required - Provide instrument_key. |
| UDAPI1009 | TransactionType is required - Provide transaction_type. |
| UDAPI1057 | The 'transaction_type' is invalid - Only BUY and SELL are accepted. |
| UDAPI1004 | Valid order type is required - Provide order_type. |
| UDAPI1056 | The 'order_type' is invalid - Only MARKET and LIMIT are accepted. |
| UDAPI1007 | Validity is required - Provide validity. |
| UDAPI1055 | The 'validity' is invalid - Only DAY is accepted. |
| UDAPI1119 | tag length exceeds limit - The tag cannot exceed 40 characters. |
| 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. |
| UDAPI1300 | Invalid US instrument - The instrument_key is not in the US instruments file. |
| UDAPI1301 | This US stock is not tradable - The stock is listed but not currently tradable. |
| UDAPI1302 | Provide exactly one of quantity or amount - Send either quantity or amount, not both and not neither. |
| UDAPI1303 | Quantity must be greater than 0 with at most 9 decimal places. |
| UDAPI1304 | Fractional quantity is not allowed for this stock - The stock has fractionable: false. Send a whole-share quantity. |
| UDAPI1305 | Amount must be greater than 0 with at most 2 decimal places. |
| UDAPI1306 | Amount orders are not allowed for this stock - Amount orders buy fractional shares, so the stock must be fractionable. |
| UDAPI1307 | Price must be greater than 0 for a limit order. |
| UDAPI1308 | Price is not allowed for a market order - Omit price or send 0. |
| UDAPI1309 | Price allows 2 decimal places at or above $1 and 4 below $1. |
| UDAPI1310 | Order value must be at least $1. |
| UDAPI1323 | Order value cannot exceed $40,000. |
| UDAPI1311 | Order size cannot exceed 999,999 - Applies to both quantity and amount. |
| UDAPI1316 | US stocks is not activated for this account - Returned with HTTP 403. |
| UDAPI1317 | US stocks order service is unavailable. Please try again later. - Returned with HTTP 423. |
| UDAPI1318 | US stocks trading is in its daily maintenance window. Please try again later. - Returned with HTTP 423. |
| UDAPI100500 | US order was rejected - The US broker rejected the request. The error message carries the broker's reason. |
| UDAPI1319 | The US order service did not confirm this request in time. Check your order book before retrying. - Returned with HTTP 500. The order may have been placed or cancelled. |
| UDAPI1322 | US market status is unavailable, so the order was not placed. Please try again later. - Returned with HTTP 423. |
Sample Code
Place a limit order by quantity
- Python
- Node.js
- Java
- PHP
- Python SDK
- Node.js SDK
- Java SDK
- PHP SDK
- .NET SDK
import requests
url = 'https://api.upstox.com/v2/us/order/place'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
}
data = {
'instrument_key': 'US_EQ|AAPL',
'transaction_type': 'BUY',
'order_type': 'LIMIT',
'quantity': 1.5,
'price': 180.25,
'validity': 'DAY',
'tag': 'my-strategy'
}
response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())
const axios = require('axios');
const url = 'https://api.upstox.com/v2/us/order/place';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
};
const data = {
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1.5,
"price": 180.25,
"validity": "DAY",
"tag": "my-strategy"
};
axios.post(url, data, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error.response ? error.response.data : 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) throws Exception {
String body = """
{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1.5,
"price": 180.25,
"validity": "DAY",
"tag": "my-strategy"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.upstox.com/v2/us/order/place"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("Authorization", "Bearer {your_access_token}")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
<?php
$url = 'https://api.upstox.com/v2/us/order/place';
$headers = [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {your_access_token}',
];
$data = [
'instrument_key' => 'US_EQ|AAPL',
'transaction_type' => 'BUY',
'order_type' => 'LIMIT',
'quantity' => 1.5,
'price' => 180.25,
'validity' => 'DAY',
'tag' => 'my-strategy'
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
echo $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.UsStocksOrderApi(upstox_client.ApiClient(configuration))
body = upstox_client.UsPlaceOrderRequest(
instrument_key='US_EQ|AAPL',
transaction_type='BUY',
order_type='LIMIT',
quantity=1.5,
price=180.25,
validity='DAY',
tag='my-strategy'
)
try:
api_response = api_instance.place_us_order(body)
print(api_response)
except ApiException as e:
print("Exception when calling UsStocksOrderApi->place_us_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.USStocksOrderApi();
let body = new UpstoxClient.UsPlaceOrderRequest("DAY", "US_EQ|AAPL", "BUY", "LIMIT");
body.quantity = 1.5;
body.price = 180.25;
body.tag = "my-strategy";
apiInstance.placeUsOrder(body, (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + JSON.stringify(data));
}
});
import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.UsOrderResponse;
import com.upstox.api.UsPlaceOrderRequest;
import com.upstox.auth.OAuth;
import io.swagger.client.api.UsStocksOrderApi;
import java.math.BigDecimal;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth OAUTH2 = (OAuth) defaultClient.getAuthentication("OAUTH2");
OAUTH2.setAccessToken("{your_access_token}");
UsStocksOrderApi apiInstance = new UsStocksOrderApi();
UsPlaceOrderRequest body = new UsPlaceOrderRequest();
body.setInstrumentKey("US_EQ|AAPL");
body.setQuantity(new BigDecimal("1.5"));
body.setPrice(new BigDecimal("180.25"));
body.setOrderType(UsPlaceOrderRequest.OrderTypeEnum.LIMIT);
body.setTransactionType(UsPlaceOrderRequest.TransactionTypeEnum.BUY);
body.setValidity(UsPlaceOrderRequest.ValidityEnum.DAY);
body.setTag("my-strategy");
try {
UsOrderResponse result = apiInstance.placeUsOrder(body);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling UsStocksOrderApi#placeUsOrder");
e.printStackTrace();
}
}
}
<?php
$config = (new Upstox\Client\Configuration())
->setAccessToken('{your_access_token}');
$apiInstance = new Upstox\Client\Api\USStocksOrderApi(
new GuzzleHttp\Client(),
$config
);
$body = new Upstox\Client\Model\UsPlaceOrderRequest();
$body->setInstrumentKey('US_EQ|AAPL');
$body->setQuantity(1.5);
$body->setPrice(180.25);
$body->setValidity('DAY');
$body->setTransactionType('BUY');
$body->setOrderType('LIMIT');
$body->setTag('my-strategy');
try {
$result = $apiInstance->placeUsOrder($body);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling USStocksOrderApi->placeUsOrder: ' . $e->getMessage();
}
using UpstoxClient.Api;
using UpstoxClient.Client;
using UpstoxClient.Extensions;
using UpstoxClient.Model;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
var host = Host.CreateDefaultBuilder()
.ConfigureApi((context, services, options) =>
{
options.AddTokens(new OAuthToken("{your_access_token}"));
}).Build();
await host.StartAsync();
var apiInstance = host.Services.GetRequiredService<IUSStocksOrderApi>();
try
{
var response = await apiInstance.PlaceUsOrderAsync(new UsPlaceOrderRequest(
quantity: 1.5m,
price: 180.25m,
validity: UsPlaceOrderRequest.ValidityEnum.DAY,
tag: "my-strategy",
instrumentKey: "US_EQ|AAPL",
transactionType: UsPlaceOrderRequest.TransactionTypeEnum.BUY,
orderType: UsPlaceOrderRequest.OrderTypeEnum.LIMIT));
Console.WriteLine(response.RawContent);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
await host.StopAsync();
Place a market order by amount
- Python
- Node.js
- Java
- PHP
- Python SDK
- Node.js SDK
- Java SDK
- PHP SDK
- .NET SDK
import requests
url = 'https://api.upstox.com/v2/us/order/place'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
}
data = {
'instrument_key': 'US_EQ|AAPL',
'transaction_type': 'BUY',
'order_type': 'MARKET',
'amount': 25,
'validity': 'DAY'
}
response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())
const axios = require('axios');
const url = 'https://api.upstox.com/v2/us/order/place';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
};
const data = {
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "MARKET",
"amount": 25,
"validity": "DAY"
};
axios.post(url, data, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error.response ? error.response.data : 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) throws Exception {
String body = """
{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "MARKET",
"amount": 25,
"validity": "DAY"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.upstox.com/v2/us/order/place"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("Authorization", "Bearer {your_access_token}")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
<?php
$url = 'https://api.upstox.com/v2/us/order/place';
$headers = [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {your_access_token}',
];
$data = [
'instrument_key' => 'US_EQ|AAPL',
'transaction_type' => 'BUY',
'order_type' => 'MARKET',
'amount' => 25,
'validity' => 'DAY'
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
echo $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.UsStocksOrderApi(upstox_client.ApiClient(configuration))
body = upstox_client.UsPlaceOrderRequest(
instrument_key='US_EQ|AAPL',
transaction_type='BUY',
order_type='MARKET',
amount=25.0,
validity='DAY'
)
try:
api_response = api_instance.place_us_order(body)
print(api_response)
except ApiException as e:
print("Exception when calling UsStocksOrderApi->place_us_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.USStocksOrderApi();
let body = new UpstoxClient.UsPlaceOrderRequest("DAY", "US_EQ|AAPL", "BUY", "MARKET");
body.amount = 25.0;
apiInstance.placeUsOrder(body, (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + JSON.stringify(data));
}
});
import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.UsOrderResponse;
import com.upstox.api.UsPlaceOrderRequest;
import com.upstox.auth.OAuth;
import io.swagger.client.api.UsStocksOrderApi;
import java.math.BigDecimal;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth OAUTH2 = (OAuth) defaultClient.getAuthentication("OAUTH2");
OAUTH2.setAccessToken("{your_access_token}");
UsStocksOrderApi apiInstance = new UsStocksOrderApi();
UsPlaceOrderRequest body = new UsPlaceOrderRequest();
body.setInstrumentKey("US_EQ|AAPL");
body.setAmount(new BigDecimal("25.0"));
body.setOrderType(UsPlaceOrderRequest.OrderTypeEnum.MARKET);
body.setTransactionType(UsPlaceOrderRequest.TransactionTypeEnum.BUY);
body.setValidity(UsPlaceOrderRequest.ValidityEnum.DAY);
try {
UsOrderResponse result = apiInstance.placeUsOrder(body);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling UsStocksOrderApi#placeUsOrder");
e.printStackTrace();
}
}
}
<?php
$config = (new Upstox\Client\Configuration())
->setAccessToken('{your_access_token}');
$apiInstance = new Upstox\Client\Api\USStocksOrderApi(
new GuzzleHttp\Client(),
$config
);
$body = new Upstox\Client\Model\UsPlaceOrderRequest();
$body->setInstrumentKey('US_EQ|AAPL');
$body->setAmount(25.0);
$body->setValidity('DAY');
$body->setTransactionType('BUY');
$body->setOrderType('MARKET');
try {
$result = $apiInstance->placeUsOrder($body);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling USStocksOrderApi->placeUsOrder: ' . $e->getMessage();
}
using UpstoxClient.Api;
using UpstoxClient.Client;
using UpstoxClient.Extensions;
using UpstoxClient.Model;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
var host = Host.CreateDefaultBuilder()
.ConfigureApi((context, services, options) =>
{
options.AddTokens(new OAuthToken("{your_access_token}"));
}).Build();
await host.StartAsync();
var apiInstance = host.Services.GetRequiredService<IUSStocksOrderApi>();
try
{
var response = await apiInstance.PlaceUsOrderAsync(new UsPlaceOrderRequest(
amount: 25.0m,
validity: UsPlaceOrderRequest.ValidityEnum.DAY,
instrumentKey: "US_EQ|AAPL",
transactionType: UsPlaceOrderRequest.TransactionTypeEnum.BUY,
orderType: UsPlaceOrderRequest.OrderTypeEnum.MARKET));
Console.WriteLine(response.RawContent);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
await host.StopAsync();