Order Processing & Event Streaming Guide | definitely

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

1. Placing an Order

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

Request Payload (POST /v3/store/order)

1 {
2   "id": 5001,
3   "plantId": 10,
4   "quantity": 2,
5   "shipDate": "2026-08-25T10:00:00.000Z",
6   "status": "placed",
7   "complete": false
8 }

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

1 GET /v3/store/order/5001 HTTP/1.1
2 Host: api.plantstore.dev
3 api_key: pk_live_98f7d6a5e4c3b2a1

Fetch Store Inventory Map

Returns a breakdown of quantity by status across all items:

1 GET /v3/store/inventory HTTP/1.1
2 Host: api.plantstore.dev
3 api_key: pk_live_98f7d6a5e4c3b2a1

Response Payload (200 OK)

1 {
2   "available": 142,
3   "pending": 18,
4   "sold": 530
5 }

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.

Subscribing to Order State Changes

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

AsyncAPI Event Payload (Order Approved)

1 {
2   "event": "order.status_changed",
3   "timestamp": "2026-08-19T17:30:00Z",
4   "data": {
5     "orderId": 5001,
6     "plantId": 10,
7     "previousStatus": "placed",
8     "newStatus": "approved",
9     "trackingNumber": "TRK-9920148X"
10   }
11 }

JavaScript WebSocket Subscriber Example

subscriber.ts

1 const socket = new WebSocket("wss://stream.plantstore.dev/v1/orders/updates?api_key=pk_live_...");
2 
3 socket.onmessage = (event) => {
4   const payload = JSON.parse(event.data);
5   console.log(`Order ${payload.data.orderId} updated to ${payload.data.newStatus}`);
6 };

4. Order Cancellation

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

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.