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

# Order Lifecycle — Amend, Cancel, Batch, and Fill History

> Retrieve, amend, cancel, and batch-cancel orders. Fetch fill history for a subaccount. Endpoints: GET, PATCH, DELETE /v1/orders and GET /v1/fills.

The `client.orders` namespace provides full lifecycle management for your open and historical orders. Use these methods to inspect order state, amend resting orders, cancel individual orders or all orders at once, submit multiple orders in a single batch request, and retrieve fill records for a subaccount.

***

## orders.get

Retrieve a single order by its ID.

**Method:** `client.orders.get(order_id)` — `GET /v1/orders/{id}`

```python theme={"dark"}
from molecule import Molecule

client = Molecule(
    base_url="https://api.molecule.trade",
    key_id="key_abc123",
    private_key="<base64-encoded-ed25519-seed>",
)

order = client.orders.get("ord_abc123")
print(order["id"], order["status"], order["qty"], order["price"])
```

<ParamField path="order_id" type="integer | string" required>
  The Molecule order ID to retrieve. Accepts either the integer ID or its string representation.
</ParamField>

***

## orders.list

List all orders for a subaccount, optionally filtered by status.

**Method:** `client.orders.list(subaccount_id, status=None)` — `GET /v1/orders`

```python theme={"dark"}
# Retrieve all open orders for a subaccount
orders = client.orders.list(subaccount_id="sa_abc123", status="OPEN")

for order in orders:
    print(order["id"], order["status"], order["instrument_id"])
```

<ParamField query="subaccount_id" type="string" required>
  The subaccount whose orders to retrieve.
</ParamField>

<ParamField query="status" type="OrderStatus">
  Optional status filter. One of `PENDING_SUBMISSION`, `OPEN`, `PARTIAL`, `FILLED`, `CANCELLED`, `REJECTED`, or `EXPIRED`. Omit to return orders across all statuses.
</ParamField>

***

## orders.amend

Amend a resting order's price, quantity, or other mutable fields.

**Method:** `client.orders.amend(order_id, **payload)` — `PATCH /v1/orders/{id}`

```python theme={"dark"}
# Reprice a resting limit order
amended = client.orders.amend(
    "ord_abc123",
    price="0.52",
    qty="8",
)
print(amended["id"], amended["price"], amended["qty"])
```

<ParamField path="order_id" type="integer | string" required>
  The ID of the order to amend. The order must be in an amendable state (`OPEN` or `PARTIAL`).
</ParamField>

<ParamField body="price" type="string">
  New limit price as a decimal string.
</ParamField>

<ParamField body="qty" type="string">
  New quantity as a decimal string. May be reduced but not increased beyond the original quantity on some venues.
</ParamField>

<Note>
  Only pass fields you want to change. Unspecified fields retain their current values.
</Note>

***

## orders.cancel

Cancel a single open order by ID.

**Method:** `client.orders.cancel(order_id)` — `DELETE /v1/orders/{id}`

```python theme={"dark"}
result = client.orders.cancel("ord_abc123")
print(result)
```

<ParamField path="order_id" type="integer | string" required>
  The ID of the order to cancel.
</ParamField>

***

## orders.cancel\_all

Cancel all open orders for a subaccount. Omit `subaccount_id` to cancel across all subaccounts.

**Method:** `client.orders.cancel_all(subaccount_id=None)` — `POST /v1/orders/cancel-all`

```python theme={"dark"}
# Cancel all open orders for a specific subaccount
client.orders.cancel_all(subaccount_id="sa_abc123")

# Cancel all open orders across all subaccounts
client.orders.cancel_all()
```

<ParamField body="subaccount_id" type="string">
  The subaccount whose open orders to cancel. Omit to cancel across all subaccounts associated with your key.
</ParamField>

<Warning>
  This action is irreversible. All resting orders for the specified scope are cancelled immediately.
</Warning>

***

## orders.batch

Submit multiple orders in a single atomic request. Useful for placing a set of related orders while minimising round-trips.

**Method:** `client.orders.batch(orders)` — `POST /v1/orders/batch`

```python theme={"dark"}
result = client.orders.batch([
    {
        "subaccount_id": "sa_1",
        "instrument_id": 42,
        "side": "BUY",
        "type": "LIMIT",
        "tif": "GTC",
        "price": "0.50",
        "qty": "5",
    },
    {
        "subaccount_id": "sa_1",
        "instrument_id": 43,
        "side": "SELL",
        "type": "LIMIT",
        "tif": "IOC",
        "price": "0.55",
        "qty": "3",
    },
])
print(result)
```

<ParamField body="orders" type="array" required>
  A list of order objects. Each object accepts the same fields as a [single order creation](/api/orders/create) payload, including `subaccount_id`, `instrument_id`, `side`, `type`, `tif`, `price`, `qty`, and `routing`.
</ParamField>

***

## orders.fills

Retrieve all fill records for a subaccount.

**Method:** `client.orders.fills(subaccount_id)` — `GET /v1/fills`

```python theme={"dark"}
fills = client.orders.fills(subaccount_id="sa_abc123")

for fill in fills:
    print(fill["order_id"], fill["price"], fill["qty"], fill["created_at"])
```

<ParamField query="subaccount_id" type="string" required>
  The subaccount whose fill history to retrieve.
</ParamField>

<Tip>
  Fill records are also accessible via `client.portfolio.fills(subaccount_id)`, which exposes the same `GET /v1/fills` endpoint. Use whichever namespace is more natural for your workflow.
</Tip>

***

## Error reference

| Exception | HTTP status | When raised |
| - | - | - |
| `NotFoundError` | 404 | Order ID does not exist or belongs to a different subaccount |
| `ValidationError` | 422 | Invalid amend payload or missing required batch fields |
| `UnauthorizedError` | 401 | Invalid or missing Ed25519 signature |
| `ForbiddenError` | 403 | Kill switch active or insufficient permissions |
| `ConflictError` | 409 | Idempotency key conflict on batch submission |
| `RateLimitedError` | 429 | Request rate limit exceeded |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.