Managing Orders

Overview

Orders represent purchases made in a Whatalo store. The Orders API lets you retrieve order details, update lifecycle state, update payment state, add internal notes, 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 Orders

PATCH /v1/orders/{id} supports three mutable fields:

status
payment_status
internal_notes

You can send one or more of these fields in the same request. Orders are otherwise read-only.

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:

pending | confirmed | in_progress | completed | cancelled | returned

Only valid state transitions succeed. For example, an order can move from pending to confirmed, but not from completed back to pending.

Update Payment Status

Update the payment state without changing the order lifecycle:

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 '{
    "payment_status": "paid"
  }'

Supported payment status values:

pending | paid | refunded | failed

Update Internal Notes

Store an internal merchant note on the order:

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 '{
    "internal_notes": "Handed to courier"
  }'

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',
        internal_notes: 'Picked up by fulfillment system'
      })
    }
  );

  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