# 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`           | KYC needed before ordering this product |
| `422`  | `insufficient_inventory` | Not enough IPs in the requested geo/ASN |
| `422`  | `quantity_out_of_range`  | Quantity below 5 or above 5000          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/api-reference/orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.