Place Multi Order Beta

This API extends the functionality of the Place Order API, allowing multiple orders to be placed simultaneously on the exchange. Each order in the request must include a unique correlation_id for individual tracking. Each successful order will return a unique order_id for further management such as modifications or cancellations.

Order Limits and Rate Limits

• A maximum of 25 orders can be placed in a single request. Any request exceeding this limit will be rejected.
• The Multi Order API is subject to a different rate limit compared to the standard limits applied across the system. For more information on the rate limits for this API, please check here.

Header Parameters

Name	Required	Type	Description
Authorization	true	string	Requires the format Bearer access_token where access_token is obtained from the Token API.
Content-Type	true	string	Indicates the media type of the resource, set as application/json.
Accept	true	string	Defines the content format the client expects, which should be set to application/json.

Request Body

[
    {
        "correlation_id": "1",
        "quantity": 25,
        "product": "D",
        "validity": "DAY",
        "price": 0,
        "tag": "string",
        "instrument_token": "NSE_FO|62864",
        "order_type": "MARKET",
        "transaction_type": "BUY",
        "disclosed_quantity": 0,
        "trigger_price": 0,
        "is_amo": false,
        "slice": false
    },
    {
        "correlation_id": "2",
        "quantity": 25,
        "product": "D",
        "validity": "DAY",
        "price": 0,
        "tag": "string",
        "instrument_token": "NSE_FO|62867",
        "order_type": "MARKET",
        "transaction_type": "BUY",
        "disclosed_quantity": 0,
        "trigger_price": 0,
        "is_amo": false,
        "slice": false
    }
]

Name	Required	Type	Description
correlation_id	true	string	Uniquely identifies each order line within the request. It must be unique per line and is echoed in responses for easy tracking of related errors or feedback. The correlation_id must not exceed 20 characters in length. Note: The correlation_id is scoped only to this request and cannot be used in another API to refer to this order line.
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.
tag	false	string	This field functions the same as in the Place Order API, but with a size restriction of 40 characters.

For all other fields, please refer to the Place Order API documentation as all fields are the same as those used when placing an order using the Place Order API.

Order Execution Sequence

In a multi-order request, the system will execute all BUY orders first, followed by the execution of all SELL orders. This ensures a consistent and orderly processing of multiple order types within the same request.

Maximum Order Limit

When slicing is applied, we calculate the total number of resulting orders. The total number of orders in a request, including those generated by the slice, must not exceed the maximum order count specified here.

Responses

• 2XX
• 4XX

---

Response Body

Success (200)

{
    "status": "success",
    "data": [
        {
            "correlation_id": "1",
            "order_id": "1644490272000"
        },
        {
            "correlation_id": "2",
            "order_id": "2134134141414"
        }
    ],
    "summary": {
        "total": 2,
        "payload_error": 0,
        "success": 2,
        "error": 0
    }
}

NOTE

In the event of payload issues with any order lines, the entire batch of orders will not be placed. Orders will only be executed when the entire array is validated and free of any payload_error. This ensures all transactions are processed without discrepancies.

Name	Type	Description
status	string	A string indicating the outcome of the request. Possible values: success, partial_success, error. success - when all order lines were placed partial_success - when some order lines encountered errors error - when all order lines encountered errors or there were issues with one or more of the payloads.
data	object	Response data for place order request
data.correlation_id	string	Mirrors the unique identifier provided for each order line in the request, facilitating easy tracking and correlation of responses with their respective orders.
data.order_id	string	An order ID for the order request placed
summary	object	A summary of the outcomes for the batch of orders processed, detailing total orders, valid submissions, successful completions, and errors.
summary.total	integer	The total number of order lines present in the payload.
summary.payload_error	integer	The number of order lines with payload errors, indicating formatting or data validity issues. Note: Orders are processed only if the entire batch is free of payload_error, ensuring error-free transactions.
summary.success	integer	The number of order lines that were successfully placed without any errors.
summary.error	integer	The number of order lines that encountered errors during processing, despite their payloads being valid.

Partial Success (207)

{
    "status": "partial_success",
    "data": [
        {
            "correlation_id": "1",
            "order_id": "1644490272000"
        }
    ],
    "errors": [
        {
            "correlation_id": "2",
            "error_code": "UDAPI100500",
            "message": "Something went wrong... please contact us",
            "property_path": null,
            "invalid_value": null
        }
    ],
    "summary": {
        "total": 2,
        "payload_error": 0,
        "success": 1,
        "error": 1
    }
}

NOTE

In the event of payload issues with any order lines, the entire batch of orders will not be placed. Orders will only be executed when the entire array is validated and free of any payload_error. This ensures all transactions are processed without discrepancies.

Name	Type	Description
status	string	A string indicating the outcome of the request. Possible values: success, partial_success, error. success when all order lines were placed, partial_success when some order lines encountered errors, and error when all order lines encountered errors or there were issues with one or more of the payloads.
data	object	Response data for place order request
data.correlation_id	string	Mirrors the unique identifier provided for each order line in the request, facilitating easy tracking and correlation of responses with their respective orders.
data.order_id	string	An order ID for the order request placed
errors	object	Array of errors including every order line that encountered an issue. For more details, refer to the Error Response documentation.
errors.correlation_id	string	Reflects the unique identifier provided for each order line in the request, aiding in tracking errors associated with specific orders.
summary	object	A summary of the outcomes for the batch of orders processed, detailing total orders, valid submissions, successful completions, and errors.
summary.total	integer	The total number of order lines present in the payload.
summary.payload_error	integer	The number of order lines with payload errors, indicating formatting or data validity issues. Note: Orders are processed only if the entire batch is free of payload_error, ensuring error-free transactions.
summary.success	integer	The number of order lines that were successfully placed without any errors.
summary.error	integer	The number of order lines that encountered errors during processing, despite their payloads being valid.

{
    "status": "error",
    "errors": [
        {
            "correlation_id": "1",
            "error_code": "UDAPI1054",
            "message": "The 'product' is invalid",
            "property_path": null,
            "invalid_value": null
        },
        {
            "correlation_id": "2",
            "error_code": "UDAPI1040",
            "message": "Price not required",
            "property_path": null,
            "invalid_value": null
        }
    ],
    "summary": {
        "total": 5,
        "payload_error": 2,
        "success": 0,
        "error": 0
    }
}

NOTE

In the event of payload issues with any order lines, the entire batch of orders will not be placed. Orders will only be executed when the entire array is validated and free of any payload_error. This ensures all transactions are processed without discrepancies.

Name	Type	Description
status	string	A string indicating the outcome of the request. Possible values: success, partial_success, error. success when all order lines were placed, partial_success when some order lines encountered errors, and error when all order lines encountered errors or there were issues with one or more of the payloads.
data	object	Response data for place order request
data.correlation_id	string	Mirrors the unique identifier provided for each order line in the request, facilitating easy tracking and correlation of responses with their respective orders.
data.order_id	string	An order ID for the order request placed
errors	object	Array of errors including every order line that encountered an issue. For more details, refer to the Error Response documentation.
errors.correlation_id	string	Reflects the unique identifier provided for each order line in the request, aiding in tracking errors associated with specific orders.
summary	object	A summary of the outcomes for the batch of orders processed, detailing total orders, valid submissions, successful completions, and errors.
summary.total	integer	The total number of order lines present in the payload.
summary.payload_error	integer	The number of order lines with payload errors, indicating formatting or data validity issues. Note: Orders are processed only if the entire batch is free of payload_error, ensuring error-free transactions.
summary.success	integer	The number of order lines that were successfully placed without any errors.
summary.error	integer	The number of order lines that encountered errors during processing, despite their payloads being valid.

Error Codes

Error Code	Description
UDAPI1114	Request payload should have at least one order line - The request must include at least one valid order line. An empty request is not allowed and will result in a rejection.
UDAPI1115	Missing correlation_id - One or more order lines in the payload are missing the required correlation_id. This field is necessary for tracking and identifying individual order lines.
UDAPI1116	Invalid correlation_id: Length must be between 1 and 20 characters. - The length of the correlation_id exceeds the permitted limit of 20 characters. Ensure each correlation_id is within the defined limit.
UDAPI1117	Duplicate correlation_id found - Each order line must have a unique correlation_id. Duplicate correlation IDs will cause the entire request to be rejected.
UDAPI1118	Maximum order limit exceeded - 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.

Please refer to the error codes listed in the Place Order API as they are also applicable here.

NOTE

The Multi order api is down for maintenance from 12:00 AM to 5:30 AM IST daily and is not available for usage during these hours. Users are advised to plan their activities accordingly.

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.

Correlation ID for Split Orders

In the case of a sliced order, the correlation_id will be returned with a suffix to uniquely identify each split order. For the use case defined above, if the correlation_id in the request was orderline25, the split orders will be returned with correlation_id values as orderline25_1, orderline25_2, and so on, up to orderline25_11. This allows for easy tracking and management of the split orders in subsequent operations or error handling.

Examples

A comprehensive set of examples is provided to illustrate various use cases and implementation scenarios for this API. To view detailed examples and access sample code, please refer to: API Examples.

Loading...