> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matambaintelligence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders

> The states an order moves through, the rules for each order type, and how cancels and fills reach you.

When you place an order, we store it, send it to the exchange once, and then track it until it reaches a final state. Every change creates an [event](/webhooks).

## Order states

```mermaid theme={"dark"}
%%{init: {"theme": "neutral"}}%%
stateDiagram-v2
    [*] --> sending
    sending --> pending
    sending --> partially_filled
    sending --> filled
    sending --> uncertain
    sending --> rejected
    sending --> refused
    sending --> cancelled
    pending --> partially_filled
    pending --> filled
    pending --> uncertain
    pending --> rejected
    pending --> cancelled
    pending --> expired
    partially_filled --> partially_filled
    partially_filled --> filled
    partially_filled --> rejected
    partially_filled --> cancelled
    partially_filled --> expired
    uncertain --> pending
    uncertain --> partially_filled
    uncertain --> filled
    uncertain --> rejected
    uncertain --> refused
    uncertain --> cancelled
    filled --> [*]
    rejected --> [*]
    refused --> [*]
    cancelled --> [*]
    expired --> [*]
```

| State              | Meaning                                                                                                                                          | Final |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| `sending`          | We've stored the order and are sending it. You normally see this only while your request is in progress.                                         | No    |
| `pending`          | The exchange has the order, and nothing has traded yet.                                                                                          | No    |
| `partially_filled` | Some shares have traded. `filled_quantity` says how many.                                                                                        | No    |
| `filled`           | All shares have traded.                                                                                                                          | Yes   |
| `uncertain`        | We sent the order and don't know whether the exchange received it. We don't send it again. See [Handling uncertain orders](/handling-uncertain). | No    |
| `rejected`         | The exchange rejected the order. `reject_reason` says why.                                                                                       | Yes   |
| `refused`          | We refused the order, and it never reached the exchange. You can place it again with a new `Idempotency-Key`.                                    | Yes   |
| `cancelled`        | The exchange confirmed a cancel.                                                                                                                 | Yes   |
| `expired`          | Its time in force ended before it filled.                                                                                                        | Yes   |

An order that ends as `cancelled`, `expired` or `rejected` can have a `filled_quantity` above zero: shares that traded before it ended. We record those fills first, so you receive an `order.partially_filled` event before the final one.

New states can be added. Treat a state you don't recognise as not final, and retrieve the order again later. See [Versioning](/versioning).

## Order types

| `type`   | Use it for          | Price                                                                                                                       |
| -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `limit`  | ETFs only.          | Send `price_kobo`, the limit price per share.                                                                               |
| `market` | Any other security. | Leave out `price_kobo`. We price the order at the day's price limit: the upper limit for a buy, the lower limit for a sell. |

The broker accepts limit orders only for ETFs. A limit order on any other security is rejected with `422 order_rejected` and `reject_reason` set to `limit_orders_etf_only`. The order is stored as `rejected`, so place a market order with a new `Idempotency-Key`.

## Time in force

| `time_in_force` | Meaning                                    |
| --------------- | ------------------------------------------ |
| `day`           | Good for the current trading session only. |
| `gtc`           | Good till cancelled.                       |
| `ioc`           | Immediate or cancel.                       |
| `fok`           | Fill or kill.                              |

We accept every `type` with every `time_in_force`. The broker decides which combinations it supports. If it doesn't support one, the order comes back as `422 order_rejected`, and `reject_reason` says why.

## Fills

We check the broker for changes to your open orders every 30 seconds. When an order fills, partly or fully, we record the change, and you receive the event within seconds of that. Expect a fill to reach you within about a minute of the trade. You can also retrieve the order with `GET /v1/orders/{id}`, which returns what we've recorded and doesn't ask the broker.

## Cancel an order

Send `DELETE /v1/orders/{id}`. You can cancel only a limit order that is `pending` or `partially_filled`.

| Response                   | Meaning                                                                                                                      | What to do                                                               |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `202`                      | The broker accepted the cancel request. The order isn't cancelled yet. The body shows the order as it was before the cancel. | Wait for `order.cancelled`, or `order.filled` if the order filled first. |
| `409 order_not_cancelable` | The order is a market order, is in a final state, isn't yet confirmed at the exchange, or the broker refused the cancel.     | Retrieve the order to see its state.                                     |
| `503 exchange_unavailable` | We didn't send the cancel.                                                                                                   | Send it again.                                                           |
| `503 cancel_unconfirmed`   | The cancel may have reached the broker.                                                                                      | Send it again. Asking twice is harmless.                                 |

## Estimate before you order

`POST /v1/orders/estimate` takes the same body as `POST /v1/orders` and returns `estimated_total_kobo` without placing anything. For a buy, it's the estimated cost. For a sell, it's the estimated proceeds. The figure is the broker's estimate and is indicative. The [quickstart](/quickstart) shows how the sandbox works it out.