Orders

Read order data and update order status using client.orders — list, get, updateStatus, and count.

client.orders lets your plugin read order data and update order lifecycle/payment status. Orders are read-only except for status transitions, which require the write:orders scope.

Required Scopes

Operation	Required Scope
`list`, `get`, `count`	`read:orders`
`updateStatus`	`write:orders`
`updatePaymentStatus`	`write:orders`

HTTP Mapping

Method	HTTP Verb	Path
`list(params?)`	GET	`/orders`
`get(id)`	GET	`/orders/:id`
`updateStatus(id, data)`	PATCH	`/orders/:id`
`updatePaymentStatus(id, data)`	PATCH	`/orders/:id`
`count(status?)`	GET	`/orders/count`

Methods

list

Retrieve a paginated list of orders, optionally filtered by status.

const { data, pagination } = await client.orders.list({
  page: 1,
  per_page: 25,
  status: "pending", // Filter by order status
});

data.forEach((order) => {
  console.log(`Order ${order.id}: ${order.status} (${order.currency} ${order.total})`);
});

get

Retrieve a single order by its ID, including line items, customer, and shipping details.

const order = await client.orders.get("order_123");

console.log(order.data.status);
console.log(order.data.payment_status);
console.log(order.data.total);
console.log(order.data.currency);

updateStatus

Transition an order to a new status. Only valid status transitions are accepted by the API.

// Confirm an order
await client.orders.updateStatus("order_123", {
  status: "confirmed",
});

// Move an order into fulfilment
await client.orders.updateStatus("order_123", {
  status: "in_progress",
});

// Cancel an order
await client.orders.updateStatus("order_123", {
  status: "cancelled",
});

Status values: pending, confirmed, in_progress, completed, cancelled, returned.

updatePaymentStatus

Update the payment state of an order.

// Mark an order as paid
await client.orders.updatePaymentStatus("order_123", {
  payment_status: "paid",
});

// Mark an order as refunded
await client.orders.updatePaymentStatus("order_123", {
  payment_status: "refunded",
});

Payment status values: pending, paid, refunded, failed.

count

Get the total number of orders, optionally filtered by status.

// Count all orders
const total = await client.orders.count();

// Count pending orders only
const pending = await client.orders.count("pending");

console.log(`${pending} orders awaiting processing`);

Typical Plugin Pattern

Most fulfillment or logistics plugins follow this pattern:

import { WhataloClient, NotFoundError } from "@whatalo/plugin-sdk";

const client = new WhataloClient({ apiKey: process.env.WHATALO_API_KEY! });

async function fulfillOrder(orderId: string): Promise<void> {
  // 1. Fetch order details
  const { data: order } = await client.orders.get(orderId);

  if (order.status !== "confirmed") {
    throw new Error(`Cannot fulfil order with status: ${order.status}`);
  }

  // 2. Send to fulfilment provider
  await myFulfilmentProvider.ship(order);

  // 3. Update order status in the store
  await client.orders.updateStatus(orderId, { status: "in_progress" });
}

Error Handling

import { NotFoundError, ValidationError } from "@whatalo/plugin-sdk";

try {
  await client.orders.updateStatus("order_999", { status: "completed" });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Order not found: ${error.resourceId}`);
  } else if (error instanceof ValidationError) {
    // Invalid status transition
    error.fieldErrors.forEach((e) => console.log(`${e.field}: ${e.message}`));
  } else {
    throw error;
  }
}

See Errors & Rate Limits for the full error class reference.

On this page