Orders
List Orders
Paginate the authenticated partner's orders.
Endpoint
GET /api/v1/orders
Query parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
state | string | No | Order state filter |
limit | number | No | Defaults to 20, capped at 100 |
cursor | string | No | Continue cursor from a previous page |
Response
Returns paginated order list:
{
"success": true,
"data": {
"orders": [
{
"_id": "kh72y10adpkj8kr1bbrgcgnvcd841w5g",
"_creationTime": 1775046434454.9124,
"createdAt": 1775046434454,
"updatedAt": 1775046435554,
"shortReference": "563967",
"beneficiaryMsisdn": "233540983543",
"operatorId": "kd7ff6sssan1v3d00dbbttwaa57yp27d",
"operatorName": "MTN",
"productId": "m17dnxcx4sww9qym18d73b5v6x7yqqah",
"productName": "enterprise-api",
"packageId": "kn79vk1wapbwx3q3z252yvr8ph7yqmct",
"packageLabel": "1 GB",
"amount": 4.25,
"currency": "GHS",
"state": "processing",
"orderType": "data",
"providerRef": "JESSCO-4175984",
"submittedAt": 1775046434454,
"completedAt": null,
"errorMessage": null,
"isBulkOrder": false
}
],
"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 |
paymentReference | string | null | Customer payment reference |
paymentGateway | string | null | Payment gateway used (if applicable) |
paymentGatewayStatus | string | null | Gateway status |
providerRef | string | null | Provider transaction reference |
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) |
Sample request
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"