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

# Order Management

## Querying Orders

### Get a Single Order

```typescript theme={null}
import { Orderbook } from '@imtbl/orderbook';

const { result: order } = await orderbook.getListing(orderId);

console.log({
  id: order.id,
  status: order.status,
  price: order.buy.amount,
  seller: order.accountAddress,
  tokenId: order.sell.tokenId,
});
```

### List Orders for a Collection

```typescript theme={null}
import { Orderbook, OrderStatusName } from '@imtbl/orderbook';

const { result } = await orderbook.listListings({
  sellItemContractAddress: NFT_CONTRACT,
  status: OrderStatusName.ACTIVE,
  pageSize: 50,
});

for (const listing of result) {
  console.log(`Token #${listing.sell.tokenId}: ${listing.buy.amount} IMX`);
}
```

### Pagination

```typescript theme={null}
let cursor: string | undefined;

do {
  const { result, page } = await orderbook.listListings({
    sellItemContractAddress: NFT_CONTRACT,
    status: OrderStatusName.ACTIVE,
    pageSize: 100,
    pageCursor: cursor,
  });
  
  for (const listing of result) {
    console.log(listing.id);
  }
  
  cursor = page.nextCursor;
} while (cursor);
```

## Order Status

For complete order status definitions and lifecycle, see [Order Lifecycle](/docs/products/orderbook/overview#order-lifecycle).

## Fill Status

For fill status details and tracking partial fills, see [Fill Orders: Fill Status](/docs/products/orderbook/fill-orders#fill-status).

## Cancelling Orders

For detailed cancellation methods, race conditions, and best practices, see [Cancel Orders](/docs/products/orderbook/cancel-orders).

## Webhooks

Get real-time notifications for order events. Configure webhooks in [Hub](https://hub.immutable.com). For implementation details, see the [webhook documentation](/docs/products/hub/webhooks).

| Event                 | Trigger              |
| --------------------- | -------------------- |
| `imtbl_order_updated` | Order status changed |
| `imtbl_activity_sale` | Trade completed      |

Webhook payloads can represent **listings**, **bids**, **collection bids**, **trait bids**, or **metadata bids**. Use the order **`type`** field (and related discriminator fields your integration already uses) to branch—for example, handle `TRAIT_BID` when you need to read **`trait_criteria`** / **`traitCriteria`** for display or analytics, or handle `METADATA_BID` when you need to read the **`metadata_id`** / **`metadataId`**.

### Webhook Payload Example

```json theme={null}
{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "order-123",
    "status": "FILLED",
    "type": "LISTING",
    "sell": {
      "type": "ERC721",
      "contract_address": "0x...",
      "token_id": "456"
    },
    "buy": {
      "type": "NATIVE",
      "amount": "1000000000000000000"
    }
  }
}
```

Trait bid payloads include the same high-level `sell` / `buy` / `status` fields and add **trait criteria**

```json theme={null}
{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "trait-bid-456",
    "status": "ACTIVE",
    "type": "TRAIT_BID",
    "trait_criteria": [
      { "trait_type": "Background", "values": ["Blue", "Red"] }
    ],
    "sell": [{ "type": "ERC20", "contract_address": "0x...", "amount": "1000000000000000000" }],
    "buy": [{ "type": "ERC721_COLLECTION", "contract_address": "0xnft...", "amount": "1" }]
  }
}
```

Metadata bid payloads include the same high-level `sell` / `buy` / `status` fields and add a **`metadata_id`**

```json theme={null}
{
  "event_name": "imtbl_order_updated",
  "data": {
    "id": "metadata-bid-789",
    "status": "ACTIVE",
    "type": "METADATA_BID",
    "metadata_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sell": [{ "type": "ERC20", "contract_address": "0x...", "amount": "1000000000000000000" }],
    "buy": [{ "type": "ERC721_COLLECTION", "contract_address": "0xnft...", "amount": "1" }]
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Listings" icon="tag" href="/docs/products/orderbook/create-listings">
    Learn how to create NFT listings
  </Card>

  <Card title="Fill Orders" icon="cart-shopping" href="/docs/products/orderbook/fill-orders">
    Buy NFTs by filling orders
  </Card>

  <Card title="Cancel Orders" icon="xmark" href="/docs/products/orderbook/cancel-orders">
    Cancel listings with soft or hard cancels
  </Card>

  <Card title="Fees" icon="percent" href="/docs/products/orderbook/fees">
    Understand fee structure and calculations
  </Card>

  <Card title="Trait bids" icon="filter" href="/docs/products/orderbook/trait-bids">
    Create and query metadata-filtered collection bids
  </Card>

  <Card title="Metadata bids" icon="fingerprint" href="/docs/products/orderbook/metadata-bids">
    Create and query metadata ID-based collection bids
  </Card>
</CardGroup>