Overview
Returns a preview of a change to an equity order.
Description

This API accepts a simulated equity order change as input and returns a preview of the modified order, with estimated costs, allowing the user to review the change before submitting it.

The preview response includes a preview ID number which must be referenced when submitting the actual change request.

URL
https://etws.etrade.com/order/rest/previewchangeequityorder
HTTP Method: POST

Since this is a POST request, the parameters are included in the request as XML or JSON.

Request Parameters
Parameter Type Required? Description
accountId integer required Numeric account ID
orderNum integer required Order number, taken from a previous response, that identifies the order to be changed
priceType enum required The type of pricing. Possible values are:
• MARKET
• LIMIT
• STOP
• STOP_LIMIT
• MARKET_ON_CLOSE
If STOP, requires a stopPrice. If LIMIT, requires a limitPrice. If STOP_LIMIT, requires both.
limitPrice double conditional The highest price at which to buy or the lowest price at which to sell. Required if priceType is LIMIT.
stopPrice double conditional The price at which to buy or sell if specified in a stop order. Required if priceType is STOP.
allOrNone boolean optional If TRUE, the transactions specified in the order must be executed all at once, or not at all. Default is FALSE.
quantity integer required The number of shares to buy or sell
reserveOrder boolean optional If TRUE, publicly displays only a limited number of shares (the reserve quantity), instead of the entire order, to avoid influencing other traders. Default is FALSE. If TRUE, must also specify the reserveQuantity.
reserveQuantity integer conditional The number of shares displayed for a reserve order. Required if reserveOrder is TRUE.
orderTerm enum required Specifies the term for which the order is in effect. Possible values are:
• GOOD_UNTIL_CANCEL
• GOOD_FOR_DAY
• IMMEDIATE_OR_CANCEL (only for limit orders)
• FILL_OR_KILL (only for limit orders)
clientOrderId string optional A reference number generated by the developer. Used to ensure that a duplicate order is not being submitted. It can be any value of 20 alphanumeric characters or less, but must be unique within this account. It does not appear in any API responses.
Response Properties
Property Type Description
accountId integer Numeric account ID
allOrNone boolean If TRUE, the transactions specified in the order must be executed all at once, or not at all.
estimatedCommission double The cost billed to the user to perform the requested action
estimatedTotalAmount double The cost or proceeds, including broker commission, resulting from the requested action
messageList complex Container for messages describing the result of the action
message complex Container for a result message
   msgDesc string Text of the result message, indicating order status, success or failure, additional requirements that must be met before placing the order, etc. Applications typically display this message to the user, which may result in further user action.
   msgCode integer Standard numeric code of the result message. Refer to the Error Messages documentation for examples. May optionally be displayed to the user, but is primarily intended for internal use.
previewTime long The time of this preview, in epoch time
previewId long Numeric preview ID
quantity integer The number of shares to buy or sell
reserveOrder boolean If TRUE, this is a reserve order - meaning that only a limited number of shares will be publicly displayed, instead of the entire order, to avoid influencing other traders.
reserveQuantity integer The number of shares to be publicly displayed if this is a reserve order
orderTerm string Specifies the term for which the order is in effect. Possible values are:
• GOOD_UNTIL_CANCEL
• GOOD_FOR_DAY
• IMMEDIATE_OR_CANCEL (only for limit orders)
• FILL_OR_KILL (only for limit orders)
priceType string The type of pricing. Possible values are:
• MARKET
• LIMIT
• STOP
• STOP_LIMIT
• MARKET_ON_CLOSE
limitPrice double The highest price at which to buy or the lowest price at which to sell if specified in a limit order. Returned if priceType is LIMIT.
stopPrice double The price at which a stock is to be bought or sold if specified in a stop order. Returned if priceType is STOP.
symbolDesc string Text description of the security being bought or sold
symbol string The market symbol for the security being bought or sold
orderAction string The action that the broker is requested to perform. Possible values are:
• BUY
• SELL
• BUY_OPEN
• SELL_OPEN
Sample Request
Request URL
POST https://etwssandbox.etrade.com/order/sandbox/rest/changeequityorder
Request Parameters - XML
<previewChangeEquityOrder xmlns="http://order.etws.etrade.com">
  <changeEquityOrderRequest>
    <accountId>83405188</accountId>
    <orderNum>16</orderNum>
    <limitPrice></limitPrice>
    <stopPrice></stopPrice>
    <allOrNone></allOrNone>
    <quantity></quantity>
    <reserveOrder></reserveOrder>
    <reserveQuantity></reserveQuantity>
    <priceType></priceType>
    <orderTerm>GOOD_UNTIL_CANCEL</orderTerm>
  </changeEquityOrderRequest>
</previewChangeEquityOrder>
Request Parameters - JSON
{
  "previewChangeEquityOrder": {
    "-xmlns": "http://order.etws.etrade.com",
    "changeEquityOrderRequest": {
      "accountId": "83405188",
      "orderNum": "16",
      "orderTerm": "GOOD_UNTIL_CANCEL"
    }
  }
}
Sample Response - XML
<PreviewChangeEquityOrderResponse>
  <equityOrderResponse>
    <accountId>83405188</accountId>
    <allOrNone>false</allOrNone>
    <estimatedCommission>7.99</estimatedCommission>
    <estimatedTotalAmount>19.99</estimatedTotalAmount>
    <messageList/>
    <orderNum>0</orderNum>
    <orderTime>1269430328285</orderTime>
    <previewTime>1269430496444</previewTime>
    <previewId>449548414022</previewId>
    <quantity>4</quantity>
    <reserveOrder>false</reserveOrder>
    <reserveQuantity>0</reserveQuantity>
    <orderTerm>GOOD_UNTIL_CANCEL</orderTerm>
    <limitPrice>3</limitPrice>
    <symbolDesc>E TRADE FINANCIAL CORP COM</symbolDesc>
    <symbol>ETFC</symbol>
    <orderAction>BUY</orderAction>
    <priceType>LIMIT</priceType>
  </equityOrderResponse>
</PreviewChangeEquityOrderResponse>
Sample response – JSON
 {
  "PreviewChangeEquityOrderResponse": {
    "equityOrderResponse": {
      "accountId": "83405188",
      "allOrNone": "FALSE",
      "estimatedCommission": "7.99",
      "estimatedTotalAmount": "19.99",
      "orderNum": "0",
      "orderTime": "1269430328285",
      "previewTime": "1269430496444",
      "previewId": "449548414022",
      "quantity": "4",
      "reserveOrder": "FALSE",
      "reserveQuantity": "0",
      "orderTerm": "GOOD_UNTIL_CANCEL",
      "limitPrice": "3",
      "symbolDesc": "E TRADE FINANCIAL CORP COM",
      "symbol": "ETFC",
      "orderAction": "BUY",
      "priceType": "LIMIT"
    }
  }
}
Notes
  • For equity and option orders, types STOP and STOP LIMIT represent the "Stop On Quote" and "Stop Limit on Quote" price types offered by E*TRADE, respectively.
  • For equity orders, use limit price for type LIMIT, stop price for type STOP, and both prices for type STOP_LIMIT. For option orders, use limit limit price for type LIMIT, stop price for type STOP, and stop-limit price for type STOP_LIMIT.
  • The clientOrderID element is used to ensure that a duplicate order is not inadvertently submitted. Within a given account, clientOrderID must be unique for every order (regardless of which APIs are used).
Sample use cases
Some possible use-cases and workflows are described below.
Purpose Workflow Related APIs
Preview changes Load a display with order details from the List Orders API. Display also shows account ID, name, and balances, as well as product fundamentals, intraday, and current (streaming) price info. In a loop, whenever the user clicks to preview the estimated cost, call the preview API, reload the display from the response, and allow the user to continue editing, commit, or quit. The application should always validate all user inputs and also check the response for error messages. Get Quote, List Accounts, Get Account Balance, Streaming API
Sandbox Samples

The following is an example of a request and response in the sandbox environment. Note that the HTTP POST method is used.

Request URL
POST https://etwssandbox.etrade.com/order/sandbox/rest/previewchangeequityorder.json
Request Parameters - JSON
{
  "previewChangeEquityOrder":{
    "-xmlns":"http://order.etws.etrade.com",
    "changeEquityOrderRequest":{
      "priceType":"",
      "orderTerm":"GOOD_UNTIL_CANCEL",
      "accountId":"83550325",
      "orderNum":"162",
      "clientOrderId":"asdf1234",
      "limitPrice":"",
      "previewId":"",
      "stopPrice":"",
      "allOrNone":"",
      "quantity":"",
      "reserveOrder":"",
      "reserveQuantity":""
    }
  }
}
Response
{
  "previewChangeEquityOrderResponse":{
    "equityOrderResponse":{
      "accountId":83405188,
      "allOrNone":false,
      "estimatedCommission":5,
      "estimatedTotalAmount":77,
      "orderNum":0,
      "orderTime":1267488794333,
      "previewTime":1267488833223,
      "previewId":499501471087,
      "quantity":4,
      "reserveOrder":false,
      "reserveQuantity":0,
      "orderTerm":"GOOD_FOR_DAY",
      "limitPrice":16,
      "stopPrice":15,
      "symbolDesc":"TD AMERITRADE HLDG CORP COM",
      "symbol":"AMTD",
      "orderAction":"BUY",
      "priceType":"STOP_LIMIT"
    }
  }
}
Related APIs
PLEASE READ THE IMPORTANT DISCLOSURES BELOW

By using E*TRADE API ("API") and accepting the terms of the Application Programming Interface License Agreement and the Application Programming Interface User Agreement, you agree that API may employ security policies, procedures and systems of Third Party providers which may or may not be less stringent and secure than the policies, procedures and systems of E*TRADE Securities LLC ("E*TRADE") or its affiliates. Material provided on API may have been produced by independent third parties not affiliated or endorsed by E*TRADE or its affiliates ("Third Party"). To the extent that API or Third Party providers express opinions or make recommendations, you understand that such opinions or recommendations are expressed by the Third Party provider and are not the opinions or recommendations of E*TRADE or its affiliates. E*TRADE is not responsible for the accuracy of market data displayed on API or made available by Third Party providers. There may be latency between the time an order (or other information) is submitted from API and the time the order is received by E*TRADE. The E*TRADE Two Second Execution Guarantee or any similar guarantee does not apply for orders placed through API and Third Party provider web sites. The E*TRADE CompleteTM Protection Guarantee does not apply. Orders created and submitted through API are not vetted until they are received by E*TRADE. It is possible that E*TRADE may reject an order placed through API. Please see the Application Programming Interface License Agreement and the Application Programming Interface User Agreement for more information.


The E*TRADE family of companies provides financial services including trading, investing, and related banking products and services to retail investors.


Securities products and services offered by E*TRADE Securities LLC, Member FINRA/SIPC.


System response and account access times may vary due to a variety of factors, including trading volumes, market conditions, system performance, and other factors.