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.

E*TRADE Developer Platform 160 Preview Equity Order Change 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)

E*TRADE Developer Platform 161 Preview Equity Order Change 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

<orderTerm>GOOD_UNTIL_CANCEL</orderTerm>

</changeEquityOrderRequest>

</previewChangeEquityOrder>

Request Parameters - JSON

{

"previewChangeEquityOrder": {

"-xmlns": "http://order.etws.etrade.com", "changeEquityOrderRequest": {

"accountId": "83405188",

E*TRADE Developer Platform 162 Preview Equity Order Change "orderNum": "16",

"orderTerm": "GOOD_UNTIL_CANCEL"

} } }

Sample Response - XML

<allOrNone>false</allOrNone>

<reserveOrder>false</reserveOrder>

<orderTerm>GOOD_UNTIL_CANCEL</orderTerm>

<symbolDesc>E TRADE FINANCIAL CORP COM</symbolDesc>

<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",

E*TRADE Developer Platform 163 Preview Equity Order Change "priceType": "LIMIT"

} } }

Notes

 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

Related APIs

Place Equity Order, Preview Equity Order Change, Preview Option Order, Get Quote, List Accounts, Get Account Balance

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":{

E*TRADE Developer Platform 164 Preview Equity Order Change "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"

} } }

E*TRADE Developer Platform 165 Place Equity Order Change

In document E*TRADE Developer Platform. Developer Guide and API Reference. October 24, 2012 API Version: v0 (Page 159-165)