Skip to main content
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 quantity in shares. Fractional quantities (up to 9 decimal places) are allowed only for stocks with fractionable: true.
  • By amount — send amount in 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 MARKET order must not carry a price. Omit price or send 0.
  • 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_OPEN is placed as an after-market order (AMO), and is_amo is true in the order book.
  • Session, funds and sell-quantity checks are done by the US broker. A failed check returns HTTP 400 with UDAPI100500 and 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​

NameRequiredTypeDescription
instrument_keyRequiredstringUS instrument key from the US instruments file, for example US_EQ|AAPL.
transaction_typeRequiredstringPossible values: BUY, SELL.
order_typeRequiredstringPossible values: MARKET, LIMIT.
validityRequiredstringPossible value: DAY.
quantityOptionalnumberNumber of shares, up to 9 decimal places. Fractions are allowed only for fractionable stocks. Send either quantity or amount.
amountOptionalnumberUSD to invest, up to 2 decimal places. Allowed only for fractionable stocks. Send either quantity or amount.
priceOptionalnumberLimit 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.
tagOptionalstringFree-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​

Response Body​

{
"status": "success",
"data": {
"order_id": "1a9ecf08-e5f8-475c-a7c0-9056826d4b18"
}
}
NameTypeDescription
statusstringOutcome of the request. Typically success.
dataobjectResponse data for the place order request.
data.order_idstringUnique order ID of the placed order.

Sample Code​

Place a limit order by quantity​

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())

Place a market order by amount​

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())