Order Events

Order events are triggered when customer orders are created, updated, change status, or are deleted.

TypeScript Interfaces

Copy these interfaces to type your webhook handlers:

Base interfaces typescript

/** Base event properties included in all webhook events */
interface BaseEvent {
  /** Unique event identifier (UUID) */
  id: string;
  /** Event type */
  kind: string;
  /** ISO 8601 timestamp */
  time: string;
  /** Transaction identifier for grouping related events */
  transactionId: string;
}

/** Order status values */
type OrderStatus =
  | "pending"
  | "confirmed"
  | "processing"
  | "shipped"
  | "delivered"
  | "cancelled";

---

order.created

Triggered when a new order is created.

Example

{
  "id": "evt_abc123",
  "kind": "order.created",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "orderId": "ord_456",
  "orderShortId": "ORD-001"
}

TypeScript

interface OrderCreatedEvent extends BaseEvent {
  kind: "order.created";
  /** Order UUID */
  orderId: string;
  /** Human-readable order ID (e.g., "ORD-001") */
  orderShortId: string;
}

---

order.updated

Triggered when order details are updated.

Example

{
  "id": "evt_abc123",
  "kind": "order.updated",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "orderId": "ord_456",
  "orderShortId": "ORD-001"
}

TypeScript

interface OrderUpdatedEvent extends BaseEvent {
  kind: "order.updated";
  /** Order UUID */
  orderId: string;
  /** Human-readable order ID (e.g., "ORD-001") */
  orderShortId: string;
}

---

order.status.changed

Triggered when an order’s status is updated.

order.statusChanged

{
  "id": "evt_abc123",
  "kind": "order.status.changed",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "orderId": "ord_456",
  "orderShortId": "ORD-001",
  "previousOrderStatus": "pending",
  "currentOrderStatus": "confirmed"
}

interface OrderStatusChangedEvent extends BaseEvent {
  kind: "order.status.changed";
  /** Order UUID */
  orderId: string;
  /** Human-readable order ID (e.g., "ORD-001") */
  orderShortId: string;
  /** Status before this change */
  previousOrderStatus: OrderStatus;
  /** New status after this change */
  currentOrderStatus: OrderStatus;
}

Status Values

Order Status

pending

string

Order created, awaiting confirmation

confirmed

string

Order confirmed

processing

string

Order being prepared

shipped

string

Order shipped

delivered

string

Order delivered

cancelled

string

Order cancelled

---

order.deleted

Triggered when an order is deleted.

order.deleted

{
  "id": "evt_abc123",
  "kind": "order.deleted",
  "time": "2024-01-15T10:30:00Z",
  "transactionId": "txn_xyz789",
  "orderId": "ord_456"
}

interface OrderDeletedEvent extends BaseEvent {
  kind: "order.deleted";
  /** Order UUID */
  orderId: string;
}

---

All Order Event Types

Union type for handling any order event:

Event handling typescript

type OrderEvent =
  | OrderCreatedEvent
  | OrderUpdatedEvent
  | OrderStatusChangedEvent
  | OrderDeletedEvent;

// Type guard for order events
function isOrderEvent(event: BaseEvent): event is OrderEvent {
  return event.kind.startsWith("order.");
}

// Example webhook handler
async function handleOrderWebhook(event: OrderEvent) {
  switch (event.kind) {
    case "order.created":
      console.log(`New order created: ${event.orderShortId}`);
      // Send order confirmation, notify warehouse, etc.
      break;

    case "order.updated":
      console.log(`Order ${event.orderShortId} was updated`);
      // Sync changes to external systems
      break;

    case "order.status.changed":
      console.log(
        `Order ${event.orderShortId} changed from ${event.previousOrderStatus} to ${event.currentOrderStatus}`
      );
      // Trigger notifications, update external systems, etc.
      break;

    case "order.deleted":
      console.log(`Order ${event.orderId} was deleted`);
      // Clean up related data in external systems
      break;
  }
}