> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.definitely.live/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.definitely.live/_mcp/server.

# Order Processing & Event Streaming Guide

The Plant Store order system processes customer purchases and synchronizes stock levels across channels. This guide covers placing orders via REST endpoints and receiving real-time event updates via AsyncAPI.

---

## Order Lifecycle Overview

```mermaid
stateDiagram-v2
    [*] --> Placed : POST /store/order
    Placed --> Approved : Payment Processed
    Approved --> Delivered : Order Shipped & Delivered
    Placed --> Cancelled : Customer Cancelled / Expired
```

---

## 1. Placing an Order

To reserve items and initiate checkout, post an order schema to `/store/order`:

```json title="Request Payload (POST /v3/store/order)"
{
  "id": 5001,
  "plantId": 10,
  "quantity": 2,
  "shipDate": "2026-08-25T10:00:00.000Z",
  "status": "placed",
  "complete": false
}
```

```bash title="cURL Example"
curl -X POST "https://api.plantstore.dev/v3/store/order" \
  -H "Content-Type: application/json" \
  -H "api_key: pk_live_98f7d6a5e4c3b2a1" \
  -d '{
    "id": 5001,
    "plantId": 10,
    "quantity": 2,
    "shipDate": "2026-08-25T10:00:00.000Z",
    "status": "placed",
    "complete": false
  }'
```

---

## 2. Tracking Order Status & Inventory

### Fetch Order by ID

```http
GET /v3/store/order/5001 HTTP/1.1
Host: api.plantstore.dev
api_key: pk_live_98f7d6a5e4c3b2a1
```

### Fetch Store Inventory Map

Returns a breakdown of quantity by status across all items:

```http
GET /v3/store/inventory HTTP/1.1
Host: api.plantstore.dev
api_key: pk_live_98f7d6a5e4c3b2a1
```

```json title="Response Payload (200 OK)"
{
  "available": 142,
  "pending": 18,
  "sold": 530
}
```

---

## 3. Real-Time AsyncAPI Event Streaming

In addition to HTTP endpoints, the platform emits asynchronous event notifications over WebSockets/Webhooks as defined in [`asyncapi.yaml`](file:///Users/sabre/Desktop/Definitely_Docs/fern/asyncapi.yaml).

### Subscribing to Order State Changes

Subscribe to `wss://stream.plantstore.dev/v1/orders/updates` to receive streaming JSON payloads whenever order statuses change:

```json title="AsyncAPI Event Payload (Order Approved)"
{
  "event": "order.status_changed",
  "timestamp": "2026-08-19T17:30:00Z",
  "data": {
    "orderId": 5001,
    "plantId": 10,
    "previousStatus": "placed",
    "newStatus": "approved",
    "trackingNumber": "TRK-9920148X"
  }
}
```

### JavaScript WebSocket Subscriber Example

```typescript title="subscriber.ts"
const socket = new WebSocket("wss://stream.plantstore.dev/v1/orders/updates?api_key=pk_live_...");

socket.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  console.log(`Order ${payload.data.orderId} updated to ${payload.data.newStatus}`);
};
```

---

## 4. Order Cancellation

To cancel an order before fulfillment, invoke `DELETE /store/order/{orderId}`:

```bash title="Delete Order"
curl -X DELETE "https://api.plantstore.dev/v3/store/order/5001" \
  -H "api_key: pk_live_98f7d6a5e4c3b2a1"
```

Deleting an order instantly returns reserved stock from `pending` status back to `available` status in the catalog.