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

# order_status

> Subscribe to real-time notifications of order status changes for your account

This topic is responsible for notifying the user every time one of its orders is updated (created, executed, canceled).

<Warning>
  This is an authenticated stream. You must provide a valid ticket from authentication to subscribe.
</Warning>

## Subscription Request

<ParamField body="method" type="string" required>
  Subscribe method. Must be `subscribe`
</ParamField>

<ParamField body="topics" type="array" required>
  Array of topics to subscribe to. Must include `order_status`

  Example: `["order_status"]`
</ParamField>

<ParamField body="ticket" type="string" required>
  Ticket created using the endpoint POST [https://api.ripio.com/trade/ticket](https://api.ripio.com/trade/ticket)
</ParamField>

## Stream Response

<ResponseField name="id" type="integer">
  Message identifier
</ResponseField>

<ResponseField name="topic" type="string">
  Topic name (always `order_status`)
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Server timestamp in milliseconds
</ResponseField>

<ResponseField name="body" type="object">
  Order status details object

  <Expandable title="Order Status Details">
    <ResponseField name="id" type="string">
      Order identifier
    </ResponseField>

    <ResponseField name="status" type="string">
      Order status: `open`, `executed_partially`, `executed_completely`, or `canceled`
    </ResponseField>

    <ResponseField name="type" type="string">
      Order type (e.g., `limit`, `market`, `stop_limit`)
    </ResponseField>

    <ResponseField name="side" type="string">
      Order side: `buy` or `sell`
    </ResponseField>

    <ResponseField name="pair" type="string">
      Trading pair code (e.g., ETH\_BRL)
    </ResponseField>

    <ResponseField name="price" type="number">
      Order price (for limit orders)
    </ResponseField>

    <ResponseField name="amount" type="number">
      Original order amount
    </ResponseField>

    <ResponseField name="executed_amount" type="number">
      Amount that has been executed
    </ResponseField>

    <ResponseField name="remaining_amount" type="number">
      Amount still pending execution
    </ResponseField>

    <ResponseField name="average_execution_price" type="number">
      Average price at which the order was executed
    </ResponseField>

    <ResponseField name="external_id" type="string">
      External order identifier (if provided during creation)
    </ResponseField>

    <ResponseField name="user_id" type="string">
      User ID (account owner)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Order creation datetime (ISO 8601 format)
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Last update datetime (ISO 8601 format)
    </ResponseField>
  </Expandable>
</ResponseField>

## Subscription Example

```json theme={null}
{
  "method": "subscribe",
  "topics": [
    "order_status"
  ],
  "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}
```

## Stream Response Example - Order Created

```json theme={null}
{
  "id": 7,
  "topic": "order_status",
  "timestamp": 1672856713677,
  "body": {
    "id": "F55E4E01-C39B-4AA7-848B-1C6A362C386E",
    "status": "open",
    "type": "limit",
    "side": "buy",
    "pair": "ETH_BRL",
    "price": 6,
    "amount": 4,
    "executed_amount": 0,
    "remaining_amount": 4,
    "average_execution_price": 0,
    "external_id": null,
    "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7",
    "created_at": "2023-01-24T17:28:32.247Z",
    "updated_at": "2023-01-24T17:28:32.247Z"
  }
}
```

## Stream Response Example - Order Partially Executed

```json theme={null}
{
  "id": 8,
  "topic": "order_status",
  "timestamp": 1672856714000,
  "body": {
    "id": "F55E4E01-C39B-4AA7-848B-1C6A362C386E",
    "status": "executed_partially",
    "type": "limit",
    "side": "buy",
    "pair": "ETH_BRL",
    "price": 6,
    "amount": 4,
    "executed_amount": 2.5,
    "remaining_amount": 1.5,
    "average_execution_price": 6,
    "external_id": null,
    "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7",
    "created_at": "2023-01-24T17:28:32.247Z",
    "updated_at": "2023-01-24T17:28:33.000Z"
  }
}
```

## Stream Response Example - Order Fully Executed

```json theme={null}
{
  "id": 9,
  "topic": "order_status",
  "timestamp": 1672856714500,
  "body": {
    "id": "F55E4E01-C39B-4AA7-848B-1C6A362C386E",
    "status": "executed_completely",
    "type": "limit",
    "side": "buy",
    "pair": "ETH_BRL",
    "price": 6,
    "amount": 4,
    "executed_amount": 4,
    "remaining_amount": 0,
    "average_execution_price": 6,
    "external_id": null,
    "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7",
    "created_at": "2023-01-24T17:28:32.247Z",
    "updated_at": "2023-01-24T17:28:33.993Z"
  }
}
```

## Order Status Lifecycle

```
open → executed_partially → executed_completely
  ↓
canceled
```

* **open**: Order created and waiting to be matched
* **executed\_partially**: Order has been partially filled
* **executed\_completely**: Order has been fully filled
* **canceled**: Order was canceled before full execution

## Key Fields

| Field                         | Description                     |
| ----------------------------- | ------------------------------- |
| **status**                    | Current order state             |
| **executed\_amount**          | How much has been filled        |
| **remaining\_amount**         | How much is still pending       |
| **average\_execution\_price** | Weighted average price of fills |
| **external\_id**              | Your custom order identifier    |

## Usage Notes

* **Authentication Required**: Requires valid ticket from WebSocket authentication
* **Real-time Updates**: Receive immediate notification when order status changes
* **Order Tracking**: Track all your orders in real-time
* **Multiple Orders**: You'll receive notifications for all your orders
* **Complete History**: Each notification includes all order details

## Use Cases

* **Order Monitoring**: Track all your orders in real-time
* **Portfolio Updates**: Update portfolio when orders execute
* **Alerts**: Trigger alerts when orders fill
* **Accounting**: Record trades as they execute
* **Automated Trading**: React to order fills programmatically