Orders
List Orders
Paginate the authenticated partner's orders.
Endpoint
GET /api/v1/orders
Query parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
orderType | string | No | Filter by order type. Defaults to data + result_checker only. Pass airtime, voice, afa, registration, top_up, result_checker, data, or all to override. |
state | string | No | Order state filter (pending, processing, completed, failed, reversed) |
limit | number | No | Defaults to 20, capped at 100 |
cursor | string | No | Continue cursor from a previous page |
Default scope
By default GET /api/v1/orders returns only data bundle and result checker orders — the two flows you can buy from this API. Pass ?orderType=all to include every type (top-ups, airtime, registrations, etc.), or pass a specific orderType to scope the page.
Invalid orderType values return 400 INVALID_ORDER_TYPE.
Response
Returns paginated order list:
{
"success": true,
"data": {
"orders": [
{
"_id": "kh72y10adpkj8kr1bbrgcgnvcd841w5g",
"_creationTime": 1775046434454.9124,
"createdAt": 1775046434454,
"updatedAt": 1775046435554,
"shortReference": "563967",
"beneficiaryMsisdn": "233541234567",
"operatorId": "kd7ff6sssan1v3d00dbbttwaa57yp27d",
"operatorName": "MTN",
"productId": "m17dnxcx4sww9qym18d73b5v6x7yqqah",
"productName": "enterprise-api",
"packageId": "kn79vk1wapbwx3q3z252yvr8ph7yqmct",
"packageLabel": "1 GB",
"amount": 4.25,
"currency": "GHS",
"state": "processing",
"orderType": "data",
"submittedAt": 1775046434454,
"completedAt": null,
"errorMessage": null,
"isBulkOrder": false,
"walletBalanceBefore": 250.00,
"walletBalanceAfter": 246.10
}
],
"isDone": true,
"continueCursor": "077b73b3eed120..."
}
}Response fields
| Field | Type | Notes |
|---|---|---|
orders | array | Array of order objects |
isDone | boolean | true if no more pages |
continueCursor | string | Pass as cursor to get the next page |
Order object fields
Each item in orders has the same shape as the single-order response:
| Field | Type | Notes |
|---|---|---|
_id | string | Order record ID |
_creationTime | number | Convex record creation timestamp (unix ms) |
createdAt | number | Order creation timestamp (unix ms) |
updatedAt | number | Last update timestamp (unix ms) |
shortReference | string | User-friendly alphanumeric order reference |
beneficiaryMsisdn | string | Recipient phone number (international format) |
operatorId | string | Operator ID |
operatorName | string | Operator name |
productId | string | Product ID |
productName | string | Product name |
packageId | string | Package ID |
packageLabel | string | Package display label (e.g. 1 GB) |
amount | number | GHS amount charged to wallet |
currency | string | Always GHS |
state | string | pending, processing, completed, failed, or reversed |
orderType | string | data, airtime, voice, afa, registration, top_up, or result_checker |
errorMessage | string | null | Error details if state is failed |
submittedAt | number | null | Submitted to provider timestamp (unix ms) |
completedAt | number | null | Order completion timestamp (unix ms) |
isBulkOrder | boolean | null | true for bulk orders |
bulkRecipients | array | null | Recipient list for bulk orders |
bulkCompletedCount | number | null | Completed recipient count (bulk) |
bulkFailedCount | number | null | Failed recipient count (bulk) |
walletBalanceBefore | number | null | Wallet GHS balance immediately before the order was charged (agent / SuperAgent orders only) |
walletBalanceAfter | number | null | Wallet GHS balance after the order was charged (agent / SuperAgent orders only) |
Sample request
GET
/api/v1/orderstry·it·livequery parameters
⚠ no api key set — request will use placeholder
curl -X GET "https://api.netconnectgh.online/api/v1/orders?state=processing&limit=20" \
-H "X-API-KEY: netconnect_live_your_secret_here" \
-H "Content-Type: application/json"Filter by order type
GET /api/v1/orders?orderType=result_checker&limit=50
GET /api/v1/orders?orderType=all
GET /api/v1/orders?orderType=airtime&state=completed