Data Bundles
Buy Bulk Data Bundles
Create one bulk order that fans out to multiple recipients.
Endpoint
POST /api/v1/data-bundles/buy-bulk
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
operatorId | operators id | Yes | Parent operator |
productId | products id | Yes | Parent product |
items | array | Yes | Between 2 and 20 recipients |
Each items[] entry contains:
| Field | Type | Required | Notes |
|---|---|---|---|
packageId | packages id | Yes | Package for this recipient |
beneficiaryMsisdn | string | Yes | Recipient phone number |
Behavior
- bulk ordering is restricted to
AgentandSuperAgent - minimum recipients:
2 - maximum recipients:
20 - each recipient is prevalidated before the order is created
- the API creates one parent order with embedded bulk recipient state
Response
Returns the bulk order summary:
{
"success": true,
"data": {
"success": true,
"message": "Bulk order created with 3 recipients. Processing...",
"orderId": "kr7...",
"shortReference": "514220",
"totalAmount": 37.5,
"recipientCount": 3
}
}Response fields
| Field | Type | Notes |
|---|---|---|
success | boolean | Always true on success |
message | string | Human-readable status message |
orderId | string | Parent order database ID |
shortReference | string | Short alphanumeric bulk order reference |
totalAmount | number | Total GHS charged for all recipients |
recipientCount | number | Number of recipients in this bulk order |
Recipient Processing
- Each recipient is submitted individually after the parent order is created
- Use the order status endpoint to monitor per-recipient progress
- Failed recipients can be retried individually
Errors
403- Only Agent and SuperAgent can create bulk orders400- Invalid request or validation failed402- Insufficient wallet balance for total amount422- Item count not between 2 and 20
Sample request
curl -X POST "https://api.netconnectgh.online/api/v1/data-bundles/buy-bulk" \
-H "X-API-KEY: netconnect_live_your_secret_here" \
-H "Content-Type: application/json" \
-d '{
"operatorId": "k57exampleoperator",
"productId": "p22exampleproduct",
"items": [
{
"packageId": "q34examplepackage",
"beneficiaryMsisdn": "233201234567"
},
{
"packageId": "q34examplepackage",
"beneficiaryMsisdn": "233209876543"
}
]
}'