Trading

Replace order

Replaces an existing pending order with a new one. The way this works is brokerage dependent, but usually involves cancelling the existing order and placing a new one. The order's brokerage_order_id may or may not change, be sure to use the one returned in the response going forward. Only supported on some brokerages

post/accounts/{accountId}/trading/replace

Path parameters

accountIdstring uuid required

Example:2bcd7cc3-e922-4976-bce1-9858296801c3

The ID of the account to execute the trade on.

Query parameters

userIdstring required

SnapTrade User ID. This is chosen by the API partner and can be any string that is a) unique to the user, and b) immutable for the user. It is recommended to NOT use email addresses for this property because they are usually not immutable.

Example:snaptrade-user-123

userSecretstring required

SnapTrade User Secret. This is a randomly generated string and should be stored securely. If compromised, please rotate it via the rotate user secret endpoint.

Example:adf2aa34-8219-40f7-a6b3-60156985cc61

Request body

brokerage_order_idstring required

Order ID returned by brokerage. This is the unique identifier for the order in the brokerage system.

The action describes the intent or side of a trade. This is either BUY or SELL for Equity symbols or BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN or SELL_TO_CLOSE for Options.

order_type'Limit' | 'Market' | 'StopLimit' | 'Stop' required

The type of order to place.

For Limit and StopLimit orders, the price field is required.
For Stop and StopLimit orders, the stop field is required.

time_in_force'FOK' | 'Day' | 'GTC' | 'IOC' required

The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. Here are the supported values:

Day - Day. The order is valid only for the trading day on which it is placed.
GTC - Good Til Canceled. The order is valid until it is executed or canceled.
FOK - Fill Or Kill. The order must be executed in its entirety immediately or be canceled completely.
IOC - Immediate Or Cancel. The order must be executed immediately. Any portion of the order that cannot be filled immediately will be canceled.

pricenumber nullable

The limit price for Limit and StopLimit orders.

symbolstring

The security's trading ticker symbol. Use the OCC symbol to replace an option order.

stopnumber nullable

The price at which a stop order is triggered for Stop and StopLimit orders.

unitsnumber

Number of shares for the order. This can be a decimal for fractional orders. Must be null if notional_value is provided.

Example request

{
  "brokerage_order_id": "66a033fa-da74-4fcf-b527-feefdec9257e",
  "order_type": "Market",
  "time_in_force": "Day",
  "price": 31.33,
  "symbol": "AAPL",
  "stop": 31.33,
  "units": 10.5
}

Response

brokerage_order_idstring

Order ID returned by brokerage. This is the unique identifier for the order in the brokerage system.

brokerage_group_order_idstring nullable

The brokerage-assigned identifier that links all orders within a complex order (OCO, OTO, OTOCO) together. Null for non-complex orders or when the brokerage does not return a group identifier.

order_role'TRIGGER' | 'CONDITIONAL' | 'PEER' nullable

The role of this order within a complex order group (OCO, OTO, OTOCO). Null for non-complex orders.

Indicates the status of an order. SnapTrade does a best effort to map brokerage statuses to statuses in this enum. Possible values include:

NONE
PENDING
ACCEPTED
FAILED
REJECTED
CANCELED
PARTIAL_CANCELED
CANCEL_PENDING
EXECUTED
PARTIAL
REPLACE_PENDING
REPLACED
EXPIRED
QUEUED
TRIGGERED
ACTIVATED

actionstring

The action describes the intent or side of a trade. This is usually BUY or SELL but can include other potential values like the following depending on the specific brokerage.

BUY
SELL
BUY_COVER
SELL_SHORT
BUY_OPEN
BUY_CLOSE
SELL_OPEN
SELL_CLOSE

total_quantitystring nullable

The total number of shares or contracts of the order. This should be the sum of the filled, canceled, and open quantities. Can be a decimal number for fractional shares.

open_quantitystring nullable

The number of shares or contracts that are still open (waiting for execution). Can be a decimal number for fractional shares.

canceled_quantitystring nullable

The number of shares or contracts that have been canceled. Can be a decimal number for fractional shares.

filled_quantitystring nullable

The number of shares or contracts that have been filled. Can be a decimal number for fractional shares.

execution_pricestring decimal nullable

The price at which the order was executed. For option orders, this represents the price per share.

limit_pricestring decimal nullable

The limit price is maximum price one is willing to pay for a buy order or the minimum price one is willing to accept for a sell order. Should only apply to Limit and StopLimit orders. For option orders, this represents the price per share.

stop_pricestring decimal nullable

The stop price is the price at which a stop order is triggered. Should only apply to Stop and StopLimit orders. For option orders, this represents the price per share.

order_typestring nullable

The type of order placed. The most common values are Market, Limit, Stop, and StopLimit. We try our best to map brokerage order types to these values. When mapping fails, we will return the brokerage's order type value.

time_in_forcestring

The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. We try our best to map brokerage time in force values to the following. When mapping fails, we will return the brokerage's time in force value.

Day - Day. The order is valid only for the trading day on which it is placed.
GTC - Good Til Canceled. The order is valid until it is executed or canceled.
FOK - Fill Or Kill. The order must be executed in its entirety immediately or be canceled completely.
IOC - Immediate Or Cancel. The order must be executed immediately. Any portion of the order that cannot be filled immediately will be canceled.
GTD - Good Til Date. The order is valid until the specified date.
MOO - Market On Open. The order is to be executed at the day's opening price.
EHP - Extended Hours P.M. The order is to be placed during extended hour trading, after markets close.

time_placedstring date-time

The time the order was placed. This is the time the order was submitted to the brokerage.

time_updatedstring date-time nullable

The time the order was last updated in the brokerage system. This value is not always available from the brokerage.

time_executedstring date-time nullable

The time the order was executed in the brokerage system. This value is not always available from the brokerage.

expiry_datestring date-time nullable

The time the order expires. This value is not always available from the brokerage.

symbolstring uuid

A unique ID for the security within SnapTrade, scoped to the brokerage account that the security belongs to. This is a legacy field and should not be used. Do not rely on this being a stable ID as it can change.

Example response

{
  "brokerage_order_id": "66a033fa-da74-4fcf-b527-feefdec9257e",
  "brokerage_group_order_id": "1234567890",
  "order_role": "TRIGGER",
  "universal_symbol": {
    "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
    "symbol": "VAB.TO",
    "raw_symbol": "VAB",
    "description": "VANGUARD CDN AGGREGATE BOND INDEX ETF",
    "currency": {
      "id": "87b24961-b51e-4db8-9226-f198f6518a89",
      "code": "USD",
      "name": "US Dollar"
    },
    "exchange": {
      "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
      "code": "TSX",
      "mic_code": "XTSE",
      "name": "Toronto Stock Exchange",
      "timezone": "America/New_York",
      "start_time": "09:30:00",
      "close_time": "16:00:00",
      "suffix": ".TO"
    },
    "type": {
      "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
      "code": "cs",
      "description": "Common Stock",
      "is_supported": true
    },
    "figi_code": "BBG000B9XRY4",
    "figi_instrument": {
      "figi_code": "BBG000B9Y5X2",
      "figi_share_class": "BBG001S5N8V8"
    },
    "currencies": [
      {
        "id": "87b24961-b51e-4db8-9226-f198f6518a89",
        "code": "USD",
        "name": "US Dollar"
      }
    ]
  },
  "option_symbol": {
    "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
    "ticker": "AAPL  261218C00240000",
    "option_type": "CALL",
    "strike_price": 240,
    "expiration_date": "2026-12-18",
    "underlying_symbol": {
      "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
      "symbol": "SPY",
      "raw_symbol": "VAB",
      "description": "SPDR S&P 500 ETF Trust",
      "currency": {
        "id": "87b24961-b51e-4db8-9226-f198f6518a89",
        "code": "USD",
        "name": "US Dollar"
      },
      "exchange": {
        "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
        "code": "ARCX",
        "mic_code": "ARCA",
        "name": "NYSE ARCA",
        "timezone": "America/New_York",
        "start_time": "09:30:00",
        "close_time": "16:00:00",
        "suffix": "None"
      },
      "type": {
        "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
        "code": "cs",
        "description": "Common Stock",
        "is_supported": true
      },
      "figi_code": "BBG000B9XRY4",
      "figi_instrument": {
        "figi_code": "BBG000B9Y5X2",
        "figi_share_class": "BBG001S5N8V8"
      },
      "currencies": [
        {
          "id": "87b24961-b51e-4db8-9226-f198f6518a89",
          "code": "USD",
          "name": "US Dollar"
        }
      ]
    }
  },
  "quote_universal_symbol": {
    "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
    "symbol": "VAB.TO",
    "raw_symbol": "VAB",
    "description": "VANGUARD CDN AGGREGATE BOND INDEX ETF",
    "currency": {
      "id": "87b24961-b51e-4db8-9226-f198f6518a89",
      "code": "USD",
      "name": "US Dollar"
    },
    "exchange": {
      "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
      "code": "TSX",
      "mic_code": "XTSE",
      "name": "Toronto Stock Exchange",
      "timezone": "America/New_York",
      "start_time": "09:30:00",
      "close_time": "16:00:00",
      "suffix": ".TO"
    },
    "type": {
      "id": "2bcd7cc3-e922-4976-bce1-9858296801c3",
      "code": "cs",
      "description": "Common Stock",
      "is_supported": true
    },
    "figi_code": "BBG000B9XRY4",
    "figi_instrument": {
      "figi_code": "BBG000B9Y5X2",
      "figi_share_class": "BBG001S5N8V8"
    },
    "currencies": [
      {
        "id": "87b24961-b51e-4db8-9226-f198f6518a89",
        "code": "USD",
        "name": "US Dollar"
      }
    ]
  },
  "quote_currency": {
    "id": "87b24961-b51e-4db8-9226-f198f6518a89",
    "code": "USD",
    "name": "US Dollar"
  },
  "total_quantity": "100",
  "open_quantity": "10",
  "canceled_quantity": "10",
  "filled_quantity": "80",
  "execution_price": "12.34",
  "limit_price": "12.34",
  "stop_price": "12.50",
  "trailing_stop": {
    "amount": "0.60"
  },
  "order_type": "Market",
  "time_placed": "2024-07-30T22:51:49.746270Z",
  "time_updated": "2024-08-05T00:05:57.409000Z",
  "time_executed": "2024-08-05T00:05:57.409000Z",
  "expiry_date": "2024-08-05T00:05:57.409000Z",
  "symbol": "2bcd7cc3-e922-4976-bce1-9858296801c3",
  "child_brokerage_order_ids": {
    "take_profit_order_id": "12345678",
    "stop_loss_order_id": "12345678"
  }
}

Changes

Changed in 6 of the 65 revisions of this API.1337

Aug 11, 2026e448d10a240f4See the full diff
- ○
  added the new BUY_TO_CLOSE enum value to the request property action
  request-property-enum-value-added
- ○
  added the new BUY_TO_OPEN enum value to the request property action
  request-property-enum-value-added
- ○
  added the new SELL_TO_CLOSE enum value to the request property action
  request-property-enum-value-added
- ○
  added the new SELL_TO_OPEN enum value to the request property action
  request-property-enum-value-added
Jun 12, 2026ee2f9f6516153See the full diff
- ▲
  the response property option_symbol/allOf[OptionsSymbol]/underlying_symbol/exchange/allOf[USExchange]/mic_code became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property quote_universal_symbol/allOf[UniversalSymbol]/exchange/allOf[Exchange]/mic_code became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property universal_symbol/allOf[UniversalSymbol]/exchange/allOf[Exchange]/mic_code became nullable for the status 200
  response-property-became-nullable
Jun 3, 202674f3fb52ef667See the full diff
- ▲
  the response property option_symbol became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property quote_currency became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property quote_universal_symbol became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property universal_symbol became nullable for the status 200
  response-property-became-nullable
- ▲
  the execution_price response's property type/format changed from number/ to string/decimal for status 200
  response-property-type-changed
- ▲
  the limit_price response's property type/format changed from number/ to string/decimal for status 200
  response-property-type-changed
- ▲
  the stop_price response's property type/format changed from number/ to string/decimal for status 200
  response-property-type-changed
Apr 28, 2026a50efb5b1c2b2See the full diff
- ○
  added the optional property brokerage_group_order_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property order_role to the response with the 200 status
  response-optional-property-added
Apr 10, 2026d9ce3acae7e11See the full diff
- ○
  added the optional property trailing_stop to the response with the 200 status
  response-optional-property-added
Mar 6, 20266a3b37154f4933See the full diff
- ▲
  the execution_price response's property type/format changed from string/decimal to number/ for status 200
  response-property-type-changed
- ▲
  the limit_price response's property type/format changed from string/decimal to number/ for status 200
  response-property-type-changed
- ▲
  the stop_price response's property type/format changed from string/decimal to number/ for status 200
  response-property-type-changed
- ●
  removed the optional property brokerage_group_order_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property order_role from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property trailing_stop from the response with the 200 status
  response-optional-property-removed
This revision also has 27 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history