Managing Orders

Overview

Orders represent purchases made in a Whatalo store. The Orders API lets you retrieve order details, update statuses, and integrate with fulfillment systems.

Orders are created by customers through the storefront. The API allows you to read and update orders, not create them directly.

List Orders

curl -X GET https://api.whatalo.com/v1/orders \
  -H "X-API-Key: wk_live_your_key_here"

Required scope: read:orders

Get a Single Order

curl -X GET https://api.whatalo.com/v1/orders/ord_abc123 \
  -H "X-API-Key: wk_live_your_key_here"

Get Order Items

Retrieve the line items for a specific order:

curl -X GET https://api.whatalo.com/v1/orders/ord_abc123/items \
  -H "X-API-Key: wk_live_your_key_here"

Update Order Status

Update the order lifecycle state with a PATCH request:

curl -X PATCH https://api.whatalo.com/v1/orders/ord_abc123 \
  -H "X-API-Key: wk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

Required scope: write:orders

Request body:

{
  "status": "confirmed"
}

Supported status values:

confirmed | in_progress | completed | cancelled | returned

Successful response:

{
  "data": {
    "id": "ord_abc123",
    "order_number": 1042,
    "status": "confirmed",
    "payment_status": "pending",
    "total": 5200,
    "created_at": "2026-03-13T01:13:19.687Z",
    "updated_at": "2026-03-13T01:18:10.120Z"
  }
}

Order Lifecycle

Orders in Whatalo follow this lifecycle:

pending → confirmed → in_progress → completed
                                   → returned
         → cancelled

payment_status values: pending | paid | refunded | failed

Common Patterns

Fulfillment Integration

Mark orders as in progress when your fulfillment system picks them up:

async function markInProgress(orderId) {
  const response = await fetch(
    `https://api.whatalo.com/v1/orders/${orderId}`,
    {
      method: 'PATCH',
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        status: 'in_progress'
      })
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to update order: ${response.status}`);
  }

  return response.json();
}

Order Count for Dashboard

curl -X GET "https://api.whatalo.com/v1/orders/count?status=pending" \
  -H "X-API-Key: wk_live_your_key_here"

On this page