Order History

Retrieve paginated order history with date and status filters.

Returns your paginated order history with optional date range and status filters. Ideal for reconciliation, dashboards, and audit trails.

Endpoint

GET/api/v1/orders

Request Headers

Headers

ParameterTypeRequiredDescription
X-Api-KeyStringYesYour API key. See Authentication.

Query Parameters

Query Params

ParameterTypeRequiredDescription
pageNumberNoPage number (1-based, default: 1).
limitNumberNoItems per page (1–100, default: 50).
statusStringNoFilter: processing, success, failed, refunded.
start_dateStringNoStart date (YYYY-MM-DD).
end_dateStringNoEnd date (YYYY-MM-DD). Max 90-day range.

90-Day Maximum

Date range cannot exceed 90 days.

Response

200OK
json
{
"success": true,
"data": {
  "orders": [
    {
      "order_id": "d7e8f9a0-...",
      "ref_id": "R-12345",
      "product_code": "MLBB-86",
      "product_name": "Mobile Legends 86 Diamonds",
      "target_id": "12345678",
      "zone_id": "1234",
      "price": 725,
      "status": "success",
      "message": "Order completed",
      "serial_number": "KAYBS-A7B2C3D4EF",
      "created_at": "2026-05-14T10:30:00.000Z",
      "completed_at": "2026-05-14T10:30:05.123Z"
    }
  ]
},
"meta": {
  "total": 156,
  "page": 1,
  "limit": 50,
  "total_pages": 4,
  "has_more": true
}
}

Field Behavior

Notes

ParameterRequiredDescription
serial_numberNoOnly populated when status = "success". Null otherwise.
completed_atNoSet only for terminal states (success/failed/refunded).
messageNoHuman-readable status message.
test ordersNoNever listed — a test order stores nothing.

The efficient way to poll

This endpoint is the recommended reconciliation tool for integrations that poll instead of receiving callbacks. ?status=processing returns every in-flight order in a single request, so your request cost is constant no matter how many orders are open:

GET /api/v1/orders?status=processing&limit=100
Approach Requests per sweep, 40 open orders
One order-status call per order 40 — exhausts a Bronze budget (30/min) immediately
One orders?status=processing call 1

Each row carries the same failure_code, failure_reason and refunded_amount as order-status, so a failed order needs no follow-up call to learn why.

Detecting completion

An order you are tracking that disappears from ?status=processing has reached a terminal state. Fetch the outcome with ?status=success / ?status=failed, or spot-check that one ref_id via order-status. Poll every 15–30 seconds; most orders settle in seconds.

Example cURL

curl -s "https://[kaybs-domain]/api/v1/orders?page=1&limit=10&status=success" \
  -H "X-Api-Key: ${KAYBS_API_KEY}"

Example (Node.js)

// Node 18+ (ESM)
const params = new URLSearchParams({ status: 'failed', page: '1', limit: '20' });
const res = await fetch(`https://[kaybs-domain]/api/v1/orders?${params}`, {
  headers: { 'X-Api-Key': process.env.KAYBS_API_KEY },
});
const data = await res.json();

Error Responses

Possible Errors

ParameterTypeRequiredDescription
INVALID_PAGINATION400Nopage ≥ 1, limit 1–100.
INVALID_DATE_RANGE400NoInvalid date format or end before start.
INVALID_STATUS_FILTER400NoInvalid status value.
PreviousOrder StatusNextBalance