> 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/subscriptions.md).

# Subscriptions

Subscriptions are recurring orders — typical for monthly traffic plans (residential / mobile) and monthly ISP renewals. The API mirrors what you'd configure in **Dashboard → Billing → Plans**.

## Endpoints

| Method  | Path                         | Purpose                                        |
| ------- | ---------------------------- | ---------------------------------------------- |
| `GET`   | `/subscriptions`             | List active subscriptions                      |
| `POST`  | `/subscriptions`             | Create a subscription                          |
| `GET`   | `/subscriptions/{id}`        | Get one                                        |
| `PATCH` | `/subscriptions/{id}`        | Modify quantity, plan tier, or cycle           |
| `POST`  | `/subscriptions/{id}/pause`  | Pause renewal (does not cancel current period) |
| `POST`  | `/subscriptions/{id}/cancel` | Cancel (effective end of period)               |

## List

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

Response:

```json
{
  "data": [
    {
      "id":           "sbn_01HX2K3PQ4M5",
      "product":      "residential",
      "plan":         "pro",
      "cycle":        "monthly",
      "gb_included":  500,
      "price_usd":    1500.00,
      "status":       "active",
      "renews_at":    "2026-06-01T00:00:00Z"
    },
    {
      "id":           "sbn_01HX2K4ABCD",
      "product":      "isp",
      "batch_id":     "bat_01HXabc",
      "cycle":        "annual",
      "quantity":     20,
      "price_usd":    1200.00,
      "status":       "active",
      "renews_at":    "2027-01-15T00:00:00Z"
    }
  ]
}
```

## Create — bandwidth subscription

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "product": "residential",
       "plan":    "pro",
       "cycle":   "monthly"
     }' \
     https://api.helodata.com/v1/subscriptions
```

Plan tiers (residential): `starter` (50 GB), `pro` (500 GB), `business` (2000 GB), `enterprise` (custom). Mobile uses the same tier names but lower GB caps.

## Create — ISP renewal subscription

ISP batches are usually auto-renewing by default after the first order. To turn auto-renew on for an existing batch:

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{
       "product":  "isp",
       "batch_id": "bat_01HXabc",
       "cycle":    "annual"           // or "monthly"
     }' \
     https://api.helodata.com/v1/subscriptions
```

Annual cycles get a 10% discount over equivalent monthly.

## Modify

Upgrade or downgrade:

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -d '{"plan": "business"}' \
     https://api.helodata.com/v1/subscriptions/sbn_01HX2K3PQ4M5
```

Upgrades are prorated for the current period. Downgrades take effect at the next renewal.

For ISP quantity changes:

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -d '{"quantity": 30}' \
     https://api.helodata.com/v1/subscriptions/sbn_01HX2K4ABCD
```

Quantity **increases** provision additional IPs immediately and are prorated. Decreases (releasing IPs) take effect at next renewal.

## Pause / cancel

```bash
# Pause — keep the current period's resources, don't renew
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subscriptions/sbn_01HX/pause

# Cancel — same effect, plus the subscription is archived
curl -X POST -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/subscriptions/sbn_01HX/cancel
```

After cancel, ISP batches enter the 7-day grace period documented in [IP management](/products/overview-2/ip-management.md#extend--renew).

## Errors

| Status | Code                    | Meaning                                                         |
| ------ | ----------------------- | --------------------------------------------------------------- |
| `409`  | `downgrade_below_usage` | Trying to downgrade below current period usage                  |
| `409`  | `already_subscribed`    | A subscription already exists for this product+plan combination |
| `422`  | `unknown_plan`          | Plan tier doesn't exist for this product                        |