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

Parameter	Type	Required	Description
`X-Api-Key`	String	Yes	Your API Key.
`X-Timestamp`	String	Yes	Current Unix timestamp in ms.
`X-Signature`	String	Yes	HMAC-SHA256 signature. Sign timestamp only.

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-...",
      "order_code": "AGN-D7E8F9A0B1C2",
      "ref_id": "R-12345",
      "product_code": "ALGAN-MLBB-86",
      "product_name": "Mobile Legends 86 Diamonds",
      "target_id": "12345678",
      "zone_id": "1234",
      "price": 25000,
      "status": "success",
      "message": "Order completed",
      "serial_number": "ALG-A1B2C3D4EF",
      "created_at": "2026-05-14T10:30:00.000Z",
      "completed_at": "2026-05-14T10:30:05.123Z",
      "failure_code": null,
      "failure_reason": null
    },
    {
      "order_id": "b4c5d6e7-...",
      "order_code": "AGN-B4C5D6E7F8A9",
      "ref_id": "R-12346",
      "product_code": "ALGAN-MLBB-86",
      "product_name": "Mobile Legends 86 Diamonds",
      "target_id": "87654321",
      "zone_id": "1234",
      "price": 25000,
      "status": "failed",
      "message": "Order failed",
      "serial_number": null,
      "created_at": "2026-05-14T10:31:00.000Z",
      "completed_at": "2026-05-14T10:31:03.402Z",
      "failure_code": "PRODUCT_UNAVAILABLE",
      "failure_reason": "The order was rejected: product not found"
    }
  ]
},
"meta": {
  "total": 156,
  "page": 1,
  "limit": 50,
  "total_pages": 4,
  "has_more": true
}
}

Field Behavior

Notes

Parameter	Required	Description
`order_code`	No	NEW: a short, human-quotable rendering of order_id (AGN- + 12 characters), for support chats and invoices. Added beside order_id, never in place of it; order_id is unchanged. If a 36-character UUID is awkward in your database or on your invoices, store this one instead: it is derived from order_id, its format is frozen so it never changes, and it is safe to show your own customers. Not an idempotency key; ref_id remains the only key we deduplicate on.
`serial_number`	No	Only populated when status = "success". Null otherwise.
`completed_at`	No	Set only for terminal states (success/failed/refunded). Stamped once, at the moment the order reached its final state, and never moved afterwards; callback delivery and retries no longer shift it. Rows completed before this change carry an approximate value.
`message`	No	Generic status sentence. Wording is unchanged and stable.
`failure_code`	No	NEW: stable failure category, or null. Same vocabulary as GET /order-status; see that page for the list. Treat it as an open set.
`failure_reason`	No	NEW: a human-readable sentence you can show your customer, or null. Never names our upstream provider.

Finding out why orders failed

GET /orders?status=failed now returns the reason for each failure inline, so you can reconcile a whole day of failures in one call instead of chasing them individually.

Example cURL

API_KEY="algan_live_..."
API_SECRET="sk_live_..."
TIMESTAMP=$(python3 -c "import time; print(int(time.time() * 1000))")
SIGNATURE=$(echo -n "${TIMESTAMP}" | \
  openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')

curl -s "https://algan.id/api/v1/orders?page=1&limit=10&status=success" \
  -H "X-Api-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Signature: ${SIGNATURE}"

Example (Node.js)

const crypto = require('crypto');
const API_KEY = 'algan_live_...';
const API_SECRET = 'sk_live_...';
const timestamp = Date.now().toString();
const signature = crypto.createHmac('sha256', API_SECRET).update(timestamp).digest('hex');

const params = new URLSearchParams({ status: 'failed', page: '1', limit: '20' });
const res = await fetch(`https://algan.id/api/v1/orders?${params}`, {
  headers: { 'X-Api-Key': API_KEY, 'X-Timestamp': timestamp, 'X-Signature': signature },
});
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.