NetConnect API Docs

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 Agent and SuperAgent
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,
    "status": "processing",
    "walletBalanceBefore": 500.00,
    "walletBalanceAfter": 462.50
  }
}

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
`status`	string	Initial order status — `"processing"`. Per-recipient progress is tracked under the parent order via the order status endpoint.
`walletBalanceBefore`	number	Wallet GHS balance immediately before this bulk order was charged
`walletBalanceAfter`	number	Wallet GHS balance after this bulk order was charged (`before - totalAmount`)

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 orders
400 - Invalid request or validation failed
402 - Insufficient wallet balance for total amount
422 - Item count not between 2 and 20

Sample request

POST/api/v1/data-bundles/buy-bulktry·it·live

request body · json

✓ valid

⚠ no api key set — request will use placeholder

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"
    }
  ]
}'

Buy Bulk Data Bundles