# 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                        |


---

# 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/subscriptions.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.