Orders

Overview

An order captures everything about a purchase — who bought it, what they bought, where to ship it, how they paid, and every status change along the way. Orders connect to customers, products, fulfillments, payments, and refunds, giving you a complete picture of each transaction.

Each order moves through a defined status lifecycle. You can create orders programmatically, track their progress, issue refunds, attach internal notes, and query the full status history for auditing.

List Orders

Retrieve orders with optional filters. Use status to find orders at a specific stage, customer_id to see a customer's purchase history, or date ranges to pull reports.

const whale = new WhaleClient("wk_live_...");

// List pending orders
const pending = await whale.orders.list({
  status: "pending",
  limit: 50
});

// List orders for a specific customer
const customerOrders = await whale.orders.list({
  customer_id: "cust_8a3b4c5d-e6f7-8901-abcd-ef2345678901"
});

// Filter by date range with pagination
const thisWeek = await whale.orders.list({
  created_after: "2026-03-03T00:00:00Z",
  created_before: "2026-03-10T23:59:59Z",
  limit: 25,
  offset: 0
});

Get Order Details

Fetch a single order by ID. The response includes line items, customer details, shipping address, payment information, and any associated fulfillments.

const order = await whale.orders.get("ord_550e8400-e29b-41d4-a716-446655440000");

// Response
{
  "object": "order",
  "id": "ord_550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "customer": {
    "id": "cust_8a3b4c5d-e6f7-8901-abcd-ef2345678901",
    "name": "Jane Cooper",
    "email": "jane@example.com"
  },
  "line_items": [
    {
      "product_id": "prod_001",
      "variant_id": "var_001",
      "name": "Ceramic Mug — Ocean Blue",
      "quantity": 2,
      "unit_price": 24.00,
      "total": 48.00
    }
  ],
  "shipping_address": {
    "line1": "123 Main St",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97201",
    "country": "US"
  },
  "payment": {
    "method": "card",
    "status": "captured",
    "amount": 53.28,
    "currency": "usd"
  },
  "fulfillments": [],
  "subtotal": 48.00,
  "tax": 5.28,
  "total": 53.28,
  "created_at": "2026-03-10T09:00:00.000Z"
}

Create an Order

Create an order by specifying the customer, line items, and shipping address. The order starts in pending status. Tax and totals are calculated automatically based on the shipping address and your store's tax configuration.

const order = await whale.orders.create({
  customer_id: "cust_8a3b4c5d-e6f7-8901-abcd-ef2345678901",
  line_items: [
    {
      product_id: "prod_001",
      variant_id: "var_001",
      quantity: 2
    },
    {
      product_id: "prod_007",
      variant_id: "var_012",
      quantity: 1
    }
  ],
  shipping_address: {
    line1: "123 Main St",
    city: "Portland",
    state: "OR",
    postal_code: "97201",
    country: "US"
  },
  shipping_method: "standard",
  notes: "Gift wrap requested"
});

// Response
{
  "object": "order",
  "id": "ord_7a2b3c4d-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "line_items": [...],
  "subtotal": 72.00,
  "shipping": 5.99,
  "tax": 7.92,
  "total": 85.91,
  "created_at": "2026-03-10T09:00:00.000Z"
}

Order Status Flow

Orders progress through a defined lifecycle. Status transitions are validated — you cannot skip steps or move backward. Each transition is timestamped and recorded in the status history for auditing.

Refunds & Voids

Issue a partial or full refund on a paid order, or void an unpaid order entirely. Refunds restore inventory automatically. Voiding cancels the order and releases any held inventory.

// Partial refund
const refund = await whale.orders.refund(
  "ord_550e8400-e29b-41d4-a716-446655440000",
  {
    amount: 24.00,
    reason: "Customer received damaged item",
    line_items: [
      { line_item_id: "li_001", quantity: 1 }
    ]
  }
);

// Response
{
  "object": "refund",
  "id": "ref_9b8c7d6e-f5a4-3210-dcba-987654321000",
  "order_id": "ord_550e8400-e29b-41d4-a716-446655440000",
  "amount": 24.00,
  "reason": "Customer received damaged item",
  "status": "processed",
  "inventory_restored": true,
  "created_at": "2026-03-10T14:30:00.000Z"
}

// Void an unpaid order
await whale.orders.void("ord_7a2b3c4d-e5f6-7890-abcd-ef1234567890");

// Response
{
  "object": "order",
  "id": "ord_7a2b3c4d-e5f6-7890-abcd-ef1234567890",
  "status": "voided",
  "voided_at": "2026-03-10T14:35:00.000Z"
}

Order Notes

Attach notes to an order for internal communication or customer-facing updates. Internal notes are only visible to staff; customer-facing notes trigger an email notification to the customer.

// Create an internal note
const note = await whale.orderNotes.create(
  "ord_550e8400-e29b-41d4-a716-446655440000",
  {
    content: "Customer called — wants to change shipping to express",
    is_internal: true
  }
);

// Create a customer-facing note
await whale.orderNotes.create(
  "ord_550e8400-e29b-41d4-a716-446655440000",
  {
    content: "Your order has been upgraded to express shipping at no extra charge.",
    is_internal: false
  }
);

// List all notes for an order
const notes = await whale.orderNotes.list(
  "ord_550e8400-e29b-41d4-a716-446655440000"
);

Status History

Every status transition is recorded with a timestamp, the user who triggered it, and an optional reason. Query the full audit trail for any order.

const history = await whale.orders.statusHistory(
  "ord_550e8400-e29b-41d4-a716-446655440000"
);

// Response
{
  "object": "list",
  "data": [
    {
      "from_status": null,
      "to_status": "pending",
      "changed_by": "api_key_wk_live_...",
      "reason": "Order created via API",
      "created_at": "2026-03-10T09:00:00.000Z"
    },
    {
      "from_status": "pending",
      "to_status": "confirmed",
      "changed_by": "system",
      "reason": "Payment captured successfully",
      "created_at": "2026-03-10T09:01:12.000Z"
    },
    {
      "from_status": "confirmed",
      "to_status": "processing",
      "changed_by": "staff_jane",
      "reason": "Fulfillment started",
      "created_at": "2026-03-10T10:15:00.000Z"
    }
  ]
}

API Reference