Orders

Orders are how you buy traffic (residential / mobile) or ISP batches. Different products use different sub-resources; both share the /orders envelope.

Common shape

curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-2026-05-28-001" \
     -d '{ "product": "residential", "gb": 50 }' \
     https://api.helodata.com/v1/orders

Response:

{
  "id":         "ord_01HX2K3PQ4M5",
  "product":    "residential",
  "status":     "completed",
  "total_usd":  225.00,
  "details":    { "gb": 50, "price_per_gb": 4.50 },
  "created_at": "2026-05-28T10:00:00Z"
}

Residential / Mobile (bandwidth)

-d '{
  "product": "residential",        // or "mobile"
  "gb":      50
}'

Bandwidth is added to your sub-user pool immediately. Traffic is consumed across all sub-users of that product.

ISP batches

ISP orders create a batch — a dedicated set of static IPs.

curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "product":  "isp",
       "country":  "us",
       "city":     "newyork",
       "asn":      7922,
       "quantity": 20,
       "months":   1,
       "subuser":  "sub_01HX2K3PQ4M5"
     }' \
     https://api.helodata.com/v1/orders

Returns the order envelope plus a batch_id you'll use to manage the IPs:

{
  "id":         "ord_01HXabc",
  "product":    "isp",
  "status":     "provisioning",
  "total_usd":  120.00,
  "details": {
    "batch_id": "bat_01HXabc",
    "quantity": 20,
    "country":  "us",
    "city":     "newyork",
    "asn":      7922,
    "expires_at": "2026-06-28T10:00:00Z"
  }
}

status transitions: provisioning → completed (typically 1–5 min, up to 24h for long-tail countries).

ISP batch lifecycle

Method	Path	Purpose
GET	/isp/batches	List batches
GET	/isp/batches/{id}	Get one batch
GET	/isp/batches/{id}/ips?format=plain|csv|json	Download IPs
POST	/isp/batches/{id}/refresh	Refresh all IPs in batch (once per period)
POST	/isp/batches/{id}/renew	Extend billing period
POST	/isp/batches/{id}/rotate-password	Change batch password
DELETE	/isp/batches/{id}	Release the entire batch
POST	/isp/ips/{ip_id}/replace	Replace one bad IP

List

curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/isp/batches

Replace one IP

curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"reason":"target-blocked"}' \
     "https://api.helodata.com/v1/isp/ips/{ip_id}/replace"

Free up to 14 days from purchase; afterwards 10% of batch per period is free. See IP management.

Renew

curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"months":1}' \
     "https://api.helodata.com/v1/isp/batches/{id}/renew"

Inventory check (before ordering)

curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/isp/inventory?country=us&asn=7922"

Returns available quantity, cities, and pricing per ASN.

Errors

Status	Code	Meaning
409	insufficient_balance	Account balance can't cover the order
409	kyc_required	Account is under a risk review; complete KYC to proceed (not required by default)
422	insufficient_inventory	Not enough IPs in the requested geo/ASN
422	quantity_out_of_range	Quantity below 5 or above 5000