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

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

Response:

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

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:

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:

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:

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

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

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