# Orders

The `orders` channel provides APIs to place and cancel orders.

## The order object

Both the `orders` message you send and the `orderResponses` message you receive contain the `Order` object payload.

The attributes that you send and receive depend on the requested action and order type.

> Order object example


```json
{ "coId":"req7",
  "type":"Limit",
  "timeInForce":"GTC",
  "side":"Buy",
  "currency":"EUR",
  "symbol":"EUR/USD",
  "size":50000.0,
  "org":"MDFFI1",
  "price":1.18923,
  "averagePrice":0.7835,
  "cumQty":50000.0,
  "execId":"FXI4110748548",
  "lastPrice":0.7835,
  "lastQty":50000.0,
  "orderId":"91529825282",
  "valueDate":"20210720",
  "tradeDate":"20210716",
  "settlCurrAmt":39175.0,
  "executionType":"TRADE",
  "leavesQty":0.0,
  "counterParty":"cptyA",
  "transactTime": 1664268780195,
  "action":"place",
  "userFullName":"user1@MAIN.C417",
  "transactTime":1628166823430,
  "status":"FILLED"
}
```

| Attribute  | Description |
|  --- | --- |
| `coId` | **string, max size 255: (required)** Client order ID assigned by the API user. |
| `type` | **string: (required)** `Market`, `Limit`, `Stop`, `StopLimit`, `Pegged`, `Algo` |
| `timeInForce` | **string: (required)** `GTC`, `IOC`, `FOK`, `GTT`, `DAY` |
| `side` | **string: (required)** `Buy` or `Sell` from the order placer's perspective and always for the dealt currency. |
| `currency` | **string: (required)** Dealt currency. |
| `symbol` | **string: (required)** Base and term currency separated by a slash "/" (for example `EUR/USD`). |
| `size` | **double: (required)** Order amount. |
| `rateId` | **string:** Unique identifier for rate. Required for Previously Quoted Orders. |
| `org` | **string (conditional):** Organization ID in Integral's system. If placing an order on behalf of another organization, this parameter is required and contains the other organization's ID. |
| `clientOrderTime` | **string:** Time the order was submitted in the format `yyyy-MM-dd HH:mm:ss,SSS Z`. |
| `account` | **string:** Your organization's account (legal entity). |
| `price` | **double:** Order's limit price. |
| `stopPrice` | **double:** Stop price for stop orders. |
| `expiryTime` | **long, max value 86399:** Expiry time when `timeInForce`=GTT. In seconds. Max value is one day (86399 seconds). |
| `targetStrategy` | **string:** `Mid`, `Fixing`, `Twap`, `LitSwitch`, `DarkSwitch` |
| `originalCoId` | **string:** The original client order ID of the order to be cancelled or replaced by this request. |
| `stopPrice` | **double:** Order's stop price (if any). |
| `execFlags` | **List of strings:** Execution strategy requested with order: `BidTrigger`: Stay on bid side, `MidTrigger`: Mid price, `OfferTrigger`: Stay on offer side |
| `minQty` | **double:** Minimum fill size (if any) in dealt currency. |
| `maxShow` | **double:** Amount of the order visible to other market participants: 0 (zero) or undefined: Hidden: Order is not visible to other customers.Equal to `size`: Display: Full order amount visible to other customers.Less than `size`: Iceberg: Only the value of `maxShow` visible. |
| `averagePrice` | **double:** Average price of all fills so far. |
| `cumQty` | **double:** Total cumulative amount filled so far. |
| `orderId` | **string:** Order ID assigned by Integral. |
| `valueDate` | **string:** Value date in the format `YYYY-MM-DD`. |
| `tradeDate` | **string:** Trade date of fill in the format `YYYY-MM-DD`. |
| `executionType` | **string:** `CANCELED`, `NEW`, `PARTIAL_FILL`, `PENDING_NEW`, `TRADE` |
| `leavesQty` | **double:** Unfilled amount as of the most recent fill. |
| `counterParty` | **string:** Counterparty organization ID. |
| `counterPartyAccount` | **string:** Counterparty legal entity ID. |
| `transactTime` | **long:** UTC time of last event on the order in milliseconds. |
| `action` | **string:** `place`, `cancel`, `cancelAll` |
| `userFullName` | **string:** Fully qualified user name of order submitting user, including namespace and organization ID in the format `userName`@`namespace`.`orgID`. |
| `status` | **string:** `RECEIVED`, `NEW`, `PARTIALLY_FILLED`, `FILLED`, `PENDING_CANCEL`, `CANCELED`, `REPLACED`, `STOPPED`, `REJECTED`, `EXPIRED`, `FAILED` |
| `reason` | **string:** Orders with `status=Failed` or `status=Failed`, the reason for failure or rejection. |
| `customerId` | **string:** Customer ID on whose behalf the order is placed. |
| `executionStartTime` | **string:** Relative time at which the strategy should start execution specified in the format `HH:MM:SS.sss`. If not specified, the strategy starts executing immediately. |
| `executionEndTime` | **string:** Absolute time in GMT at which the strategy should stop executing in the format `yyyy-MM-dd HH:mm:ss,SSS Z`. If not specified, the order expires based on the value of its time in force. |
| `pegPriceType` | **string:** Mid: Pegged to mid rate. |
| `pegOffsetValue` | **double:** The amount in pips that is added to the price of the peg. Can be positive or negative. |
| `actionOnExpiry` | **string:** Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap |
| `sliceSize` | **double:** TWAP order: The fixed size of each slice. |
| `passiveTime` | **int:** Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides `passiveTimeFactor`. |
| `passiveTimeFactorPercentage` | **double:** Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if `passiveTime` is not set |
| `sliceInterval` | **int:** TWAP order: Interval between slices. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values. |
| `randomizeSliceSizePercentage` | **double:** The percentage range that the `sliceSize` is randomized. |
| `randomizeSliceIntervalPercentage` | **double:** The percentage range that the `sliceInterval` is randomized. |
| `tobRange` | **double:** If `sliceSize` undefined, the slice size is this percentage of the top-of-book price size. |


## Place order

Place a new order. You can place various types of order such as limit, market, stop, algo, pegged, and more. Under algo orders you can execute various strategies such as TWAP.

> Place limit order (GTC) example


```json
{ "orders": 
  [ { "coId":"Order25",
      "type":"Limit",
      "side":"Buy",
      "symbol":"EUR/USD",
      "currency":"EUR",
      "size":1000000,
      "price":1.1867,
      "timeInForce":"GTC"
    }
  ]
}
```

> Request body


`{ "orders":["order object"] }`

> Request parameters


The required attributes on the `order` object depend on the order type.

| Order Type  | Required Attributes |
|  --- | --- |
| Limit(GTC) | `coId, type=Limit, side, symbol, size, price, currency,` `timeInForce=GTC` |
| Limit(GTT) | `coId, type=Limit, side, symbol, size, price, currency,` `timeInForce=GTT, expiryTime` |
| Market(GTT) | `coId, type=Market, side, symbol, size, price, currency,` `timeInForce=GTT, expiryTime` |
| Place: Stop | `coId, type=Stop, side, symbol, size, price, currency,` `stopPrice, timeInForce, execFlags=BidTrigger| OfferTrigger| MidTrigger` |


> Place order response filled example


```json
{"orderResponses":[
    { "coId":"Mid9",
      "type":"Algo",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1000000.0,
      "org":"C417",
      "averagePrice":1.18642,
      "cumQty":1000000.0,
      "execId":"FXI9190073000",
      "lastPrice":1.18642,
      "lastQty":1000000.0,
      "orderId":"4793444872",
      "valueDate":"20210809",
      "tradeDate":"20210805",
      "settlCurrAmt":1186420.0,
      "executionType":"TRADE",
      "leavesQty":0.0,
      "counterParty":"cptyA",
      "userFullName":"user1@MAIN.C417",
      "transactTime":1628166823430,
      "status":"FILLED"
    }
  ]
}
```

> Place order response partially filled example


```json
{ "orderResponses":[
    { "coId":"Ord2010",
      "type":"Limit",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":2.0E7,
      "org":"MDFFI1",
      "price":1.18,
      "averagePrice":0.78353,
      "cumQty":1.7509931E7,
      "execId":"FXI4111742910",
      "lastPrice":0.78353,
      "lastQty":7509931.0,
      "orderId":"91530726273",
      "valueDate":"20210722",
      "tradeDate":"20210720",
      "settlCurrAmt":5884256.24,
      "executionType":"TRADE",
      "leavesQty":2490069.0,
      "counterParty":"cptyB",
      "userFullName":"user1@MAIN.MDFFI1",
      "transactTime":"1628339623535",
      "status":"PARTIALLY_FILLED"
    }
  ]
}
```

> Response body


`{ "orderResponses":["order object"] }`

When placing orders, you receive `orderResponses` messages with different `status` values for a successful order.

See the [order](#the-order-object) object for the full list of parameter details.

| Attribute  | Description |
|  --- | --- |
| `coId` | **string:** Client order ID assigned by the API user. |
| `type` | **string:** `Market`, `Limit`, `Stop`, `StopLimit`, `Pegged`, `Algo` |
| `timeInForce` | **string:** `GTC`, `IOC`, `FOK`, `GTT`, `DAY` |
| `side` | **string:** `Buy` or `Sell` from the order placer's perspective and always for the base currency. |
| `currency` | **string:** Dealt currency. |
| `symbol` | **string:** Base and term currency separated by a slash "/" (for example `EUR/USD`). |
| `size` | **double:** Order amount. |
| `status` | **string:** `New`, `Partially Filled`, `Filled`, `Cancelled`, `Pending Cancel`, `Stopped`, `Rejected`, `Pending New`, `Expired`, `Received` |
| `executionType` | **string:** `CANCELED`, `NEW`, `PARTIAL_FILL`, `PENDING_NEW`, `TRADE` |
| `rateId` | **string:** Unique identifier for rate. Required for Previously Quoted Orders. |
| `org` | **string:** Your organization ID in Integral's system. |
| `price` | **double:** Order's limit price. |
| `expiryTime` | **long:** Expiry time when `timeInForce`=GTT. In seconds. Max value is one day (86399 seconds). |
| `maxShow` | **double:** Amount of the order visible to other market participants: 0 (zero) or undefined: Hidden: Order is not visible to other customers.Equal to `size`: Display: Full order amount visible to other customers.Less than `size`: Iceberg: Only the value of `maxShow` visible. |
| `averagePrice` | **double:** Average price of all fills so far. |
| `cumQty` | **double:** Total cumulative amount filled so far. |
| `execId` | **string:** Transaction ID assigned by Integral for each fill. |
| `lastPrice` | **double:** Price of the most recent fill. |
| `lastQty` | **double:** Size of the most recent fill. |
| `orderId` | **string:** Order ID assigned by Integral. |
| `valueDate` | **string:** Value date. |
| `tradeDate` | **string:** Trade date of fill. |
| `settlCurrAmt` | **double:** Amount of the settled currency. |
| `leavesQty` | **double:** Unfilled amount as of the most recent fill. |
| `counterParty` | **string:** Counterparty organization ID. |


## Amend order

Amend an active order by price, by size, or both.

> Order amend request example


```json
{ "orderAmendRequests":[
    { "price":"1.0",
      "size":"1000",
      "notes":"amend 2 - price",
      "coId":"clOrderIdRefABC",
      "orderId":"4890131159"
    }
  ]
}
```

> Request body


`{ "orderAmendRequests":["order object"] }`

| Attribute  | Description |
|  --- | --- |
| `price` | **double:** New order limit price. You must specify this attribute, `size`, or both. |
| `size` | **double:** New order amount. You must specify this attribute, `price`, or both. |
| `notes` | **string, max size 255:** Any notes on the order entered by the order submitting user. |
| `coId` | **string:** Client order ID assigned by the API user. |
| `orderId` | **string: (required)** Order ID assigned by Integral. |


> Amend request acknowledge example


```json
{ "orderAmendResponses":[
    { "status":"RECEIVED",
      "orderId":"4890131159",
      "coId":"clOrderIdRefABC",
      "price":1.0,
      "size":1000.0,
      "notes":"amend 2 - price"
    }
  ]
}
```

> Amend request response example SUCCESS


```json
{ "orderAmendResponses":[
    { "status":"SUCCESS",
      "orderId":"4890131159",
      "coId":"clOrderIdRefABC",
      "price":1.0,
      "size":1000.0,
      "notes":"amend 2 - price"
    }
  ]
}
```

> Amend request response example FAIL


```json
{ "orderAmendResponses":[
    { "status":"FAILURE",
      "orderId":"4890131159",
      "coId":"clOrderIdRefABC",
      "price":1.0,
      "size":1000.0,
      "notes":"amend 2 - price"
    }
  ]
}
```

## Cancel order

Cancel a single active order.

> Order cancel request example


```json
{ "orders":[
    { "action":"cancel",
      "coId":"108",
      "requestId":"req6",
      "side":"Sell",
      "symbol":"EUR/USD",
      "size":1000000
    }
  ]
}
```

> Request body


`{ "orders":["order object"] }`

You must set `action=cancel` on the `order` object.

- Action
- Required Attributes
|-|-|


- Cancel order
- `action=cancel, coId, requestId, side, symbol, size`


> Cancel response pending example


```json
{ "orderResponses":[
    { "type":"Limit",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1.0E7,
      "org":"SanityOrg",
      "price":0.3,
      "averagePrice":0.0,
      "cumQty":0.0,
      "execId":"0",
      "orderId":"NONE",
      "executionType":"PENDING_CANCEL",
      "leavesQty":1.0E7,
      "requestId":"req6",
      "action":"place",
      "userFullName":"user1@MAIN.MDFFI1",
      "status":"PENDING_CANCEL"
    }
  ]
}
```

> Cancel response verified example


```json
{ "orderResponses":[
    { "type":"Limit",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1.0E7,
      "org":"SanityOrg",
      "price":0.3,
      "averagePrice":0.0,
      "cumQty":0.0,
      "execId":"0",
      "orderId":"NONE",
      "executionType":"PENDING_CANCEL",
      "leavesQty":1.0E7,
      "requestId":"req6",
      "userFullName":"user1@MAIN.MDFFI1",
      "action":"place",
      "status":"CANCELED"
    }
  ]
}
```

> Response body


Your cancel request is acknowledged with a HTTP 202 Accepted message with no HTTP body.

Subsequent status changes are sent `orderResponses` messages.

`{ "orderResponses":["order object"] }`

You receive multiple `orderResponses` messages in response to a cancel request.

- Status
- Description
|-|-|


- `status=Pending Cancel`
- Order cancel is being attempted. The `orderResponses` message confirms your order attributes with a `clientOrderTime` timestamp.


- `status=Canceled`
- Order has been cancelled.


## Cancel all orders

Cancel all active orders.

> Cancel all request example


```json
{ "orders":[
    { "action":"cancelAll",
      "requestId":"cancel_all_51"
    }
  ]
}
```

> Request body


`{ "orders":["order object"] }`

You must set `action=cancelAll` on the `order` object.

- Action
- Required Attributes
|-|-|


- Cancel all active orders
- `action=cancelAll, requestId`


> Cancel all response received example


```json
{ "orderResponses":[
    { "org":"SanityOrg",
      "clientOrderTime":"Aug 4, 2021 11:03:38 AM",
      "requestId":"cancel_all_51",
      "action":"cancelAll",
      "status":"Received"
    }
  ]
}
```

> Cancel all response canceled order example


```json
{ "orderResponses":[
    { "type":"Stop",
      "timeInForce":"GTC",
      "side":"Sell",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1000000.0,
      "org":"order",
      "account":"SanityOrgLE",
      "price":1.18644,
      "stopPrice":1.19353,
      "maxShow":1000000.0,
      "averagePrice":0.0,
      "cumQty":0.0,
      "execId":"FXI9189599068",
      "lastPrice":0.0,
      "orderId":"4792995049",
      "executionType":"Canceled",
      "leavesQty":1000000.0,
      "requestId":"Stop21",
      "action":"place",
      "status":"CANCELED"
    }
  ]
}
```

> Cancel all response summary example


```json
{ "orderCancelReport":
  { "totalAffectedOrders":6,
    "noAffectedOrders":6,
    "requestId":"cancel_all_51"
  }
}
```

> Response body


`{ "orderResponses":["order object"] }`

You receive multiple `orderResponses` messages in response to a request to cancel all active orders:

- Status
- Description
|-|-|


- `status=Received`
- Request to cancel all received.


- `status=Canceled`
- Order canceled. Received for each canceled order.


- N/A
- Summary of mass cancel.