> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/api-reference/orders.md).

# 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

```bash
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:

```json
{
  "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)

```bash
-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.

```bash
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:

```json
{
  "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

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

### Replace one IP

```bash
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](/products/overview-2/ip-management.md).

### Renew

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

## Inventory check (before ordering)

```bash
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                                                    |