Orders
Get Order
Return one full order record if it belongs to the authenticated partner.
Endpoint
GET /api/v1/orders/{orderId}
Path parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
orderId | orders id | Yes | Order identifier |
Response
Returns the sanitised public order record:
{
"success": true,
"data": {
"_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,
"paymentReference": null,
"paymentGateway": null,
"paymentGatewayStatus": null,
"isBulkOrder": false,
"bulkRecipients": null,
"bulkCompletedCount": null,
"bulkFailedCount": null
}
}Response fields
| 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 (e.g. MTN, AT, Telecel) |
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 (offline-first flows) |
paymentGateway | string | null | Payment gateway used (if applicable) |
paymentGatewayStatus | string | null | Gateway status: pending, completed, failed, etc. |
providerRef | string | null | Downstream provider transaction reference |
submittedAt | number | null | Timestamp when submitted to provider (unix ms) |
completedAt | number | null | Timestamp when order completed (unix ms) |
isBulkOrder | boolean | null | true for bulk orders |
bulkRecipients | array | null | Recipient details for bulk orders (see below) |
bulkCompletedCount | number | null | Number of completed recipients in a bulk order |
bulkFailedCount | number | null | Number of failed recipients in a bulk order |
Bulk recipient fields (bulkRecipients[])
| Field | Type | Notes |
|---|---|---|
beneficiaryMsisdn | string | Recipient phone number |
packageId | string | Package ID for this recipient |
packageLabel | string | Package label (e.g. 1 GB) |
amount | number | Amount charged for this recipient |
status | string | pending, processing, completed, or failed |
providerRef | string | null | Provider reference for this recipient |
errorMessage | string | null | Error message if failed |
submittedAt | number | null | Submission timestamp (unix ms) |
completedAt | number | null | Completion timestamp (unix ms) |
Errors
404- Order not found or belongs to different user403- Insufficient permissions