0
# Order Management
1

2
Complete order lifecycle management including placement, modification, cancellation, order book access, and trade history. Supports regular orders, GTT (Good Till Triggered) orders, and batch operations.
3

4
## Capabilities
5

6
### Order Placement
7

8
Place various types of trading orders with comprehensive parameter support.
9

10
```python { .api }
11
def place_order(body: PlaceOrderRequest, api_version: str) -> PlaceOrderResponse:
12
    """
13
    Place a new trading order.
14
    
15
    Parameters:
16
    - body: Order details and parameters
17
    - api_version: API version ('2.0')
18
    
19
    Returns:
20
    PlaceOrderResponse with order_id and status
21
    """
22

23
def place_multi_order(body: MultiOrderRequest) -> MultiOrderResponse:
24
    """
25
    Place multiple orders in a single batch request.
26
    
27
    Parameters:
28
    - body: List of order requests
29
    
30
    Returns:
31
    MultiOrderResponse with individual order results
32
    """
33
```
34

35
#### Usage Example
36

37
```python
38
from upstox_client.api import OrderApi
39
from upstox_client.models import PlaceOrderRequest
40
from upstox_client import Configuration, ApiClient
41

42
# Setup
43
config = Configuration()
44
config.access_token = 'your_access_token'
45
api_client = ApiClient(config)
46
order_api = OrderApi(api_client)
47

48
# Place a limit order
49
order_request = PlaceOrderRequest(
50
    quantity=10,
51
    product="I",  # Intraday
52
    validity="DAY",
53
    price=1500.0,
54
    tag="my_order_tag",
55
    instrument_token="NSE_EQ|INE002A01018",  # Reliance Industries
56
    order_type="LIMIT",
57
    transaction_type="BUY",
58
    disclosed_quantity=0,
59
    trigger_price=0,
60
    is_amo=False
61
)
62

63
order_response = order_api.place_order(order_request, api_version='2.0')
64
order_id = order_response.data.order_id
65
print(f"Order placed successfully. Order ID: {order_id}")
66

67
# Place a market order
68
market_order = PlaceOrderRequest(
69
    quantity=5,
70
    product="D",  # Delivery
71
    validity="DAY", 
72
    price=0,  # Not needed for market orders
73
    tag="market_buy",
74
    instrument_token="NSE_EQ|INE009A01021",  # Infosys
75
    order_type="MARKET",
76
    transaction_type="BUY",
77
    disclosed_quantity=0,
78
    trigger_price=0,
79
    is_amo=False
80
)
81

82
market_response = order_api.place_order(market_order, api_version='2.0')
83
```
84

85
### Order Modification
86

87
Modify existing orders with updated parameters.
88

89
```python { .api }
90
def modify_order(body: ModifyOrderRequest, api_version: str) -> ModifyOrderResponse:
91
    """
92
    Modify an existing order.
93
    
94
    Parameters:
95
    - body: Modified order parameters
96
    - api_version: API version ('2.0')
97
    
98
    Returns:
99
    ModifyOrderResponse with updated order details
100
    """
101
```
102

103
#### Usage Example
104

105
```python
106
from upstox_client.models import ModifyOrderRequest
107

108
# Modify order price and quantity
109
modify_request = ModifyOrderRequest(
110
    quantity=15,  # New quantity
111
    validity="DAY",
112
    price=1520.0,  # New price
113
    order_id="240906000000123",  # Order ID to modify
114
    order_type="LIMIT",
115
    disclosed_quantity=0,
116
    trigger_price=0
117
)
118

119
modify_response = order_api.modify_order(modify_request, api_version='2.0')
120
print(f"Order modified: {modify_response.data.order_id}")
121
```
122

123
### Order Cancellation
124

125
Cancel individual orders or multiple orders in batch.
126

127
```python { .api }
128
def cancel_order(order_id: str, api_version: str) -> CancelOrderResponse:
129
    """
130
    Cancel a specific order.
131
    
132
    Parameters:
133
    - order_id: ID of order to cancel
134
    - api_version: API version ('2.0')
135
    
136
    Returns:
137
    CancelOrderResponse with cancellation status
138
    """
139

140
def cancel_multi_order() -> CancelOrExitMultiOrderResponse:
141
    """
142
    Cancel multiple orders in batch.
143
    
144
    Returns:
145
    CancelOrExitMultiOrderResponse with batch operation results
146
    """
147

148
def exit_positions() -> CancelOrExitMultiOrderResponse:
149
    """
150
    Exit all open positions by placing opposite orders.
151
    
152
    Returns:
153
    CancelOrExitMultiOrderResponse with exit operation results
154
    """
155
```
156

157
#### Usage Example
158

159
```python
160
# Cancel specific order
161
cancel_response = order_api.cancel_order(
162
    order_id="240906000000123", 
163
    api_version='2.0'
164
)
165
print(f"Order cancelled: {cancel_response.data.order_id}")
166

167
# Exit all positions
168
exit_response = order_api.exit_positions()
169
print(f"Positions exited: {len(exit_response.data)} operations")
170
```
171

172
### Order Book & Trade History
173

174
Access order book, order details, and trade execution history.
175

176
```python { .api }
177
def get_order_book(api_version: str) -> GetOrderBookResponse:
178
    """
179
    Retrieve all orders for the trading day.
180
    
181
    Parameters:
182
    - api_version: API version ('2.0')
183
    
184
    Returns:
185
    GetOrderBookResponse with list of orders
186
    """
187

188
def get_order_details(api_version: str) -> GetOrderDetailsResponse:
189
    """
190
    Get detailed information about orders.
191
    
192
    Parameters:
193
    - api_version: API version ('2.0')
194
    
195
    Returns:
196
    GetOrderDetailsResponse with comprehensive order data
197
    """
198

199
def get_trade_history(api_version: str) -> GetTradeResponse:
200
    """
201
    Retrieve trade execution history.
202
    
203
    Parameters:
204
    - api_version: API version ('2.0')
205
    
206
    Returns:
207
    GetTradeResponse with executed trades
208
    """
209

210
def get_trades_by_order(order_id: str, api_version: str) -> GetTradeResponse:
211
    """
212
    Get all trades for a specific order.
213
    
214
    Parameters:
215
    - order_id: Order ID to get trades for
216
    - api_version: API version ('2.0')
217
    
218
    Returns:
219
    GetTradeResponse with trades for the order
220
    """
221
```
222

223
#### Usage Example
224

225
```python
226
# Get all orders
227
order_book = order_api.get_order_book(api_version='2.0')
228
for order in order_book.data:
229
    print(f"Order {order.order_id}: {order.status} - {order.tradingsymbol}")
230

231
# Get trade history
232
trades = order_api.get_trade_history(api_version='2.0')
233
for trade in trades.data:
234
    print(f"Trade: {trade.tradingsymbol} - {trade.quantity} @ {trade.price}")
235
```
236

237
### Enhanced Order Management (V3 API)
238

239
Advanced order management with improved performance and features.
240

241
```python { .api }
242
def place_order(body: PlaceOrderV3Request, origin: str = None) -> PlaceOrderV3Response:
243
    """
244
    Place a new trading order using V3 API.
245
    
246
    Parameters:
247
    - body: Order details and parameters (required)
248
    - origin: Order origin identifier (optional)
249
    
250
    Returns:
251
    PlaceOrderV3Response with order placement result
252
    """
253

254
def modify_order(body: ModifyOrderRequest, origin: str = None) -> ModifyOrderV3Response:
255
    """
256
    Modify an existing order using V3 API.
257
    
258
    Parameters:
259
    - body: Order modification parameters (required)
260
    - origin: Order origin identifier (optional)
261
    
262
    Returns:
263
    ModifyOrderV3Response with modification result
264
    """
265

266
def cancel_order(order_id: str, origin: str = None) -> CancelOrderV3Response:
267
    """
268
    Cancel an existing order using V3 API.
269
    
270
    Parameters:
271
    - order_id: Unique identifier of the order to cancel (required)
272
    - origin: Order origin identifier (optional)
273
    
274
    Returns:
275
    CancelOrderV3Response with cancellation result
276
    """
277
```
278

279
#### Usage Example
280

281
```python
282
from upstox_client.api import OrderApiV3
283
from upstox_client.models import PlaceOrderV3Request
284

285
# V3 API for enhanced order management
286
order_api_v3 = OrderApiV3(api_client)
287

288
# Place order using V3 API
289
order_request_v3 = PlaceOrderV3Request(
290
    quantity=100,
291
    product="D",
292
    validity="DAY",
293
    price=1500.0,
294
    tag="v3_order",
295
    instrument_token="NSE_EQ|INE002A01018",
296
    order_type="LIMIT",
297
    transaction_type="BUY",
298
    disclosed_quantity=0,
299
    trigger_price=0.0,
300
    is_amo=False
301
)
302

303
order_response_v3 = order_api_v3.place_order(order_request_v3)
304
print(f"V3 Order placed: {order_response_v3.data.order_id}")
305

306
# Cancel order using V3 API
307
cancel_response_v3 = order_api_v3.cancel_order(order_response_v3.data.order_id)
308
print(f"Order cancelled: {cancel_response_v3.status}")
309
```
310

311
### GTT Orders (Good Till Triggered)
312

313
Advanced order types that remain active until triggered by market conditions.
314

315
```python { .api }
316
def place_gtt_order(body: GttPlaceOrderRequest) -> GttTriggerOrderResponse:
317
    """
318
    Place a GTT (Good Till Triggered) order.
319
    
320
    Parameters:
321
    - body: GTT order parameters with trigger conditions
322
    
323
    Returns:
324
    GttTriggerOrderResponse with GTT order details
325
    """
326

327
def modify_gtt_order(body: GttModifyOrderRequest) -> GttTriggerOrderResponse:
328
    """
329
    Modify an existing GTT order.
330
    
331
    Parameters:
332
    - body: Updated GTT order parameters
333
    
334
    Returns:
335
    GttTriggerOrderResponse with modified GTT details
336
    """
337

338
def cancel_gtt_order(body: GttCancelOrderRequest) -> GttTriggerOrderResponse:
339
    """
340
    Cancel a GTT order.
341
    
342
    Parameters:
343
    - body: GTT cancellation request
344
    
345
    Returns:
346
    GttTriggerOrderResponse confirming cancellation
347
    """
348

349
def get_gtt_order_details() -> GetGttOrderResponse:
350
    """
351
    Get details of all GTT orders.
352
    
353
    Returns:
354
    GetGttOrderResponse with GTT order information
355
    """
356
```
357

358
#### Usage Example
359

360
```python
361
from upstox_client.api import OrderApiV3
362
from upstox_client.models import GttPlaceOrderRequest, GttRule
363

364
# V3 API for GTT orders
365
order_api_v3 = OrderApiV3(api_client)
366

367
# Create GTT rule
368
gtt_rule = GttRule(
369
    instrument_token="NSE_EQ|INE002A01018",
370
    trigger_type="single",  # or 'ocp' for OCO-Plus
371
    trigger_values=[1600.0],  # Trigger price
372
    exchange="NSE"
373
)
374

375
# Place GTT order
376
gtt_request = GttPlaceOrderRequest(
377
    rules=[gtt_rule],
378
    quantity=10,
379
    price=1605.0,
380
    product="D",
381
    validity="GTT",
382
    order_type="LIMIT",
383
    transaction_type="SELL"
384
)
385

386
gtt_response = order_api_v3.place_gtt_order(gtt_request)
387
print(f"GTT Order placed: {gtt_response.data.gtt_order_id}")
388

389
# Get GTT order details
390
gtt_details = order_api_v3.get_gtt_order_details()
391
for gtt_order in gtt_details.data:
392
    print(f"GTT Order: {gtt_order.id} - Status: {gtt_order.status}")
393
```
394

395
## Request/Response Types
396

397
```python { .api }
398
class PlaceOrderRequest:
399
    quantity: int  # Number of shares/units
400
    product: str  # 'I' (Intraday), 'D' (Delivery), 'M' (Margin), 'CO' (Cover Order), 'BO' (Bracket Order)
401
    validity: str  # 'DAY', 'IOC' (Immediate or Cancel), 'GTT' (Good Till Triggered)
402
    price: float  # Order price (0 for market orders)
403
    tag: str  # Custom tag for order identification
404
    instrument_token: str  # Format: "EXCHANGE_SEGMENT|TOKEN" (e.g., "NSE_EQ|INE002A01018")
405
    order_type: str  # 'MARKET', 'LIMIT', 'SL' (Stop Loss), 'SL-M' (Stop Loss Market)
406
    transaction_type: str  # 'BUY', 'SELL'
407
    disclosed_quantity: int  # Quantity to disclose (0 for full disclosure)
408
    trigger_price: float  # Trigger price for SL orders (0 if not applicable)
409
    is_amo: bool  # After Market Order flag
410

411
class ModifyOrderRequest:
412
    quantity: int
413
    validity: str
414
    price: float
415
    order_id: str  # Order ID to modify
416
    order_type: str
417
    disclosed_quantity: int
418
    trigger_price: float
419

420
class MultiOrderRequest:
421
    orders: list[PlaceOrderRequest]  # List of orders to place
422

423
class GttPlaceOrderRequest:
424
    rules: list[GttRule]  # GTT trigger rules
425
    quantity: int
426
    price: float
427
    product: str
428
    validity: str
429
    order_type: str
430
    transaction_type: str
431

432
class GttRule:
433
    instrument_token: str
434
    trigger_type: str  # 'single', 'ocp' (OCO-Plus)
435
    trigger_values: list[float]  # Trigger prices
436
    exchange: str
437

438
class PlaceOrderResponse:
439
    status: str
440
    data: PlaceOrderData
441

442
class PlaceOrderData:
443
    order_id: str  # Unique order identifier
444
    
445
class GetOrderBookResponse:
446
    status: str
447
    data: list[OrderBookData]
448

449
class OrderBookData:
450
    order_id: str
451
    exchange: str
452
    instrument_token: str
453
    tradingsymbol: str  # Trading symbol (e.g., "RELIANCE")
454
    product: str
455
    order_type: str
456
    transaction_type: str
457
    quantity: int
458
    price: float
459
    trigger_price: float
460
    disclosed_quantity: int
461
    validity: str
462
    status: str  # 'open', 'complete', 'cancelled', 'rejected', 'modify_pending'
463
    tag: str
464
    filled_quantity: int
465
    pending_quantity: int
466
    average_price: float
467
    order_timestamp: str
468
    exchange_order_id: str
469
    parent_order_id: str
470

471
class GetTradeResponse:
472
    status: str
473
    data: list[TradeData]
474

475
class TradeData:
476
    exchange: str
477
    instrument_token: str
478
    tradingsymbol: str
479
    order_id: str
480
    exchange_order_id: str
481
    trade_id: str
482
    transaction_type: str
483
    quantity: int
484
    price: float
485
    trade_timestamp: str
486

487
class GttTriggerOrderResponse:
488
    status: str
489
    data: GttOrderData
490

491
class GttOrderData:
492
    gtt_order_id: str
493
    trigger_id: str
494
    status: str
495
```
496

497
## Common Order Parameters
498

499
### Product Types
500
- `"I"` - Intraday: Square off before market close
501
- `"D"` - Delivery: Hold for delivery
502
- `"M"` - Margin: Margin trading
503
- `"CO"` - Cover Order: Intraday with compulsory stop loss
504
- `"BO"` - Bracket Order: Intraday with target and stop loss
505

506
### Order Types
507
- `"MARKET"` - Execute at best available price
508
- `"LIMIT"` - Execute at specified price or better
509
- `"SL"` - Stop Loss: Trigger when price reaches trigger_price
510
- `"SL-M"` - Stop Loss Market: Market order when triggered
511

512
### Validity Types
513
- `"DAY"` - Valid for the trading day
514
- `"IOC"` - Immediate or Cancel
515
- `"GTT"` - Good Till Triggered (for GTT orders)
516

517
### Instrument Token Format
518
Format: `"EXCHANGE_SEGMENT|TOKEN"`
519

520
Examples:
521
- `"NSE_EQ|INE002A01018"` - Reliance Industries on NSE Equity
522
- `"BSE_EQ|INE002A01018"` - Reliance Industries on BSE Equity  
523
- `"NSE_FO|46942"` - Futures/Options on NSE
524
- `"MCX_FO|249736"` - Commodity futures on MCX
525

526
### Error Handling
527

528
```python
529
from upstox_client.rest import ApiException
530

531
try:
532
    order_response = order_api.place_order(order_request, api_version='2.0')
533
except ApiException as e:
534
    print(f"Order placement failed: {e.status} - {e.reason}")
535
    # Handle different error scenarios
536
    if e.status == 400:
537
        print("Invalid order parameters")
538
    elif e.status == 403:
539
        print("Insufficient permissions or margin")
540
    elif e.status == 429:
541
        print("Rate limit exceeded")
542
```
543

544
Common order errors:
545
- `400 Bad Request`: Invalid order parameters
546
- `403 Forbidden`: Insufficient margin or permissions
547
- `422 Unprocessable Entity`: Business rule violations
548
- `429 Too Many Requests`: Rate limit exceeded