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
Request Headers
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
X-Api-Key | String | Yes | Your API key. See Authentication. |
Query Parameters
Query Params
| Parameter | Type | Required | Description |
|---|---|---|---|
page | Number | No | Page number (1-based, default: 1). |
limit | Number | No | Items per page (1–100, default: 50). |
status | String | No | Filter: processing, success, failed, refunded. |
start_date | String | No | Start date (YYYY-MM-DD). |
end_date | String | No | End date (YYYY-MM-DD). Max 90-day range. |
90-Day Maximum
Date range cannot exceed 90 days.
Response
{
"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
| Parameter | Required | Description |
|---|---|---|
serial_number | No | Only populated when status = "success". Null otherwise. |
completed_at | No | Set only for terminal states (success/failed/refunded). |
message | No | Human-readable status message. |
test orders | No | Never 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
| Parameter | Type | Required | Description |
|---|---|---|---|
INVALID_PAGINATION | 400 | No | page ≥ 1, limit 1–100. |
INVALID_DATE_RANGE | 400 | No | Invalid date format or end before start. |
INVALID_STATUS_FILTER | 400 | No | Invalid status value. |