Modify Order

This document provides instructions on how to use the Modify Order API within the Firstock trading platform.

Overview

The Modify Order API is a key feature that allows traders to update certain fields of their active orders without having to cancel and re-create them. Typical use cases include changing from a limit order to a different limit price, updating the product type, or increasing/decreasing quantity.

Key benefits:

• Real-Time Adjustments: Adapt to market movements quickly by modifying open orders.
• Efficiency: Avoid the overhead of canceling and placing a new order.
• Flexibility: Change price type, trigger price, quantity, and more.

Endpoint & Method

URL:

https://api.firstock.in/V1/modifyOrder

Headers:

Body:

Below is the JSON body for the Modify Order API request. Fields marked Mandatory must be included.

Request:

{
  "userId": "{{userId}}",
  "jKey": "{{jKey}}",
  "orderNumber": "25042100011120",
  "priceType": "LMT",
  "tradingSymbol": "IDEA-EQ",
  "price": "418",
  "triggerPrice": "0",
  "quantity": "1",
  "product": "C",
  "retention": "DAY",
  "mkt_protection": "0.5"
}

Example cURL Request

curl --location 'https://api.firstock.in/V1/modifyOrder' \
--header 'Content-Type: application/json' \
--data '{
    "userId": "{{userId}}",
    "jKey": "{{jKey}}",
    "orderNumber": "25042100011120",
    "priceType": "LMT",
    "tradingSymbol": "IDEA-EQ",
    "price": "418",
    "triggerPrice": "0",
    "quantity": "1",
    "product": "C",
    "retention": "DAY",
    "mkt_protection": "0.5"
}'

Response Structure

Success Response:

If the order is successfully modified, you will receive a 200 OK status with a JSON object containing:

• status: Typically "success".
• message: A brief description (e.g., "Order modification details").
• data: Holds the updated order information or any relevant remarks.

Key Fields within data:

• orderNumber: The identifier of the order you attempted to cancel.
• rejreason: If the order could not be modified (e.g., already filled or canceled), the reason is listed here.
• remarks: Additional info, such as "Insufficient Balance" or other warnings.
• requestTime: Timestamp of when the modify request was processed.

Failure Response:

If any required field is missing, invalid, or the order can’t be canceled, you may receive a 400 or 401 status code with an error structure:

• Invalid or missing jKey: "failed".
• Order not modifiable: Already fully executed, canceled, or rejected..
• Parameter mismatch: e.g., providing a price for a market order when priceType is "MKT".

Response

        {
          "status": "success",
          "message": "Order modification details",
          "data": {
             "orderNumber": "25042100011120",
             "rejreason": "SAF:order is not open to modify",
             "requestTime": "18:07:09 21-04-2025"
          }        
  }
        

                    {
    "status": "failed",
    "code": "400",
    "name": "BAD_REQUEST",
    "error": {
      "field": "orderNumber",
      "message": "required field is empty or missing: orderNumber"
    }
  }
                

Usage & Best Practices

• Check Order Status
  • Only “open” orders can typically be modified. If an order is already filled or canceled, the modification request will fail.
• Partial Fills
  • For orders partially filled, you can adjust the remaining quantity, but note that already filled shares won’t be affected.
• Parameter Consistency
  • Ensure priceType, price, and triggerPrice are logically consistent (e.g., if priceType is "MKT", price should be 0).
• Product & Exchange Rules
  • Make sure the product type ("C", "M", "I", etc.) is valid for the exchange you’re trading on. Some product types might not be supported everywhere.
• Retry Logic
  • If you receive a transient error (e.g., network issues), implement retry logic carefully, ensuring you aren’t duplicating requests.
• Audit & Logs
  • Always log your modification attempts (orderNumber, date/time, and changes made) for compliance and debugging.

Conclusion

The Modify Order API is pivotal for active traders who need to adjust orders in response to shifting market conditions. By updating price, quantity, or other parameters on the fly, you maintain greater control over your trades. Always validate that the order is still open or partially filled before attempting modifications and ensure session credentials (jKey) are current.