Paid Subservers
Section titled “Paid Subservers”A paid subserver is a server you buy by the month: a slice of a shared machine like the free server, with larger limits from its plan. You deploy computers on it by its server ID, next to your free server and any server you rent. Plus costs $10 and Pro $25 per month; Pricing lists their limits.
A free server cannot be upgraded in place, and buying a paid subserver does not change it. For more room, buy a paid subserver, move your computers onto it with a cross-server copy, then delete the originals.
set -eo pipefail
# 1. List the plans and pick a plan version IDhoody servers plans list
# 2. Quote it: check available, and set CHARGE_CENTS to the quote's charge_centshoody servers plans quote "$PLAN_ID" -o json
# 3. Buy it with the quoted charge as the ceiling (prompts before charging).# The key is kept in BUY_KEY, or made once and printed. No answer?# Resend with the same key, or check `hoody servers subscriptions list`# before buying again. After a refusal, unset BUY_KEY for a new key.# Unset this key after the operation is resolved and before starting# another operation of the same kind.BUY_KEY="${BUY_KEY:-buy-$(date +%s)}"echo "idempotency key: $BUY_KEY"hoody servers subscriptions buy \ --plan-id "$PLAN_ID" \ --idempotency-key "$BUY_KEY" \ --max-charge-cents "$CHARGE_CENTS" \ -o json# Non-interactive (agents, CI): add -y to skip the prompt.
# 4. Follow the purchase until result is succeeded or failed:# hoody servers jobs get <operation-id> (.operation.id in the JSON buy answer)# Do not rerun this block to check on it: without BUY_KEY it buys again.import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const plans = await client.api.servers.plans.list();const planId = plans.data.plans?.[0]?.id;if (!planId) throw new Error('No plan ID returned');
const quote = await client.api.servers.plans.quote({ plan_id: planId });if (!quote.data.available) throw new Error('This plan cannot be bought right now');
// Keep the key: a resend after no answer reuses it and is charged once.// After a refusal, a retry needs a new key. Unset this key after the operation// is resolved and before starting another operation of the same kind.const idempotencyKey = process.env.BUY_KEY ?? crypto.randomUUID();console.log('idempotency key:', idempotencyKey);const bought = await client.api.servers.subscriptions.buy({ plan_id: planId, idempotency_key: idempotencyKey, max_charge_cents: quote.data.charge_cents,});
const operationId = bought.data.operation?.id;if (!operationId) throw new Error('No operation ID returned');const op = await client.api.servers.getJob(operationId);console.log(op.data.result); // null while delivery runs, then 'succeeded' or 'failed'set -eo pipefail
# 1. List the planscurl -fsS "https://api.hoody.com/api/v1/subserver-plans" \ -H "Authorization: Bearer $HOODY_TOKEN"
# 2. Quote one plan versioncurl -fsS "https://api.hoody.com/api/v1/subserver-subscriptions/quote?plan_id=$PLAN_ID" \ -H "Authorization: Bearer $HOODY_TOKEN"
# 3. Buy it with the quote's charge_cents as CHARGE_CENTS; on an error the# body names its code. No answer? Resend with the same key. After a# refusal, unset BUY_KEY for a new key. Unset this key after the# operation is resolved and before starting another operation of the same kind.BUY_KEY="${BUY_KEY:-buy-$(date +%s)}"echo "idempotency key: $BUY_KEY"curl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/subserver-subscriptions" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"plan_id": "'"$PLAN_ID"'", "idempotency_key": "'"$BUY_KEY"'", "max_charge_cents": '"$CHARGE_CENTS"'}'
# 4. Follow the purchase: GET /api/v1/subserver-operations/<operation-id># (data.operation.id in the buy answer). Do not rerun this block to check# on it: without BUY_KEY it buys again.What a paid subserver gives you
Section titled “What a paid subserver gives you”Every plan limit (CPU, RAM, disk and its speed, network speed, computers, aliases, Bot URLs, storage shares) applies to the whole subserver, shared by its computers; snapshots count per computer (what each counts). CPU and RAM are a ceiling on a shared machine, not reserved hardware, with no swap. Once your account has held a paid subserver of any plan, it can use up to 50 realms and keeps that limit after the subserver ends; the limit is for the whole account, not the subserver (realm limits).
As on the free server, computers are isolated from other customers but share hardware; for a machine allocated to you alone, rent a server. Virtual machines (KVM) and server commands need a whole machine and are not available here.
Check a plan before you buy
Section titled “Check a plan before you buy”When Hoody changes a plan’s price or resources, it publishes a new version. Your subscription keeps the version you bought, with its price, resources and hold period at every renewal; upgrade to move to the current one.
A listed plan is not always for sale: the quote’s available says whether you can buy it now (quote fields).
Choose a region
Section titled “Choose a region”You can choose where a paid subserver runs when you buy it. List the regions for the plan first. Each one has a region code, a country, a city and available, which says whether the plan can be bought there now.
Pass the code as region on the quote and on the purchase. Leave region out for Automatic: Hoody picks a region that has room. The quote’s region shows where the subserver would go.
The Hub calls the region Location (buy in the Hub).
If the region you chose is full, the purchase is refused with 409 NO_PAID_CAPACITY_IN_REGION and nothing is charged. Hoody never puts the subserver in another region instead. Choose another region, or leave region out, and retry with a new idempotency_key.
A subserver never changes region: upgrades and renewals keep it where it is. To move, buy a subserver in the other region, move your computers to it with a cross-server copy, then cancel the old one.
set -eo pipefail
# 1. List the regions for the plan, and set REGION to an available one's region codehoody servers plans regions "$PLAN_ID" -o json
# 2. Quote the plan there: check available, and set CHARGE_CENTS to charge_centshoody servers plans quote "$PLAN_ID" --region "$REGION" -o json
# 3. Buy it there (prompts before charging). Same key rules as any purchase:# resend with the same key after no answer; after a refusal, unset BUY_KEY# for a new key. Unset this key after the operation is resolved and# before starting another operation of the same kind.BUY_KEY="${BUY_KEY:-buy-$(date +%s)}"echo "idempotency key: $BUY_KEY"hoody servers subscriptions buy \ --plan-id "$PLAN_ID" \ --region "$REGION" \ --idempotency-key "$BUY_KEY" \ --max-charge-cents "$CHARGE_CENTS" \ -o json# Non-interactive (agents, CI): add -y to skip the prompt.import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const planId = process.env.PLAN_ID!;
const regions = await client.api.servers.plans.listRegions({ plan_id: planId });const region = regions.data.regions?.find((r) => r.available)?.region;if (!region) throw new Error('No region has room for this plan right now');
const quote = await client.api.servers.plans.quote({ plan_id: planId, region });if (!quote.data.available) throw new Error('This plan cannot be bought there right now');
// Keep the key: a resend after no answer reuses it and is charged once.// After a refusal, a retry needs a new key. Unset this key after the operation// is resolved and before starting another operation of the same kind.const idempotencyKey = process.env.BUY_KEY ?? crypto.randomUUID();console.log('idempotency key:', idempotencyKey);const bought = await client.api.servers.subscriptions.buy({ plan_id: planId, region, idempotency_key: idempotencyKey, max_charge_cents: quote.data.charge_cents,});console.log(bought.data.subscription?.region); // { region, country, city }set -eo pipefail
# 1. List the regions for the plancurl -fsS "https://api.hoody.com/api/v1/subserver-subscriptions/regions?plan_id=$PLAN_ID" \ -H "Authorization: Bearer $HOODY_TOKEN"
# 2. Quote the plan in one region (REGION is a region code from step 1)curl -fsS "https://api.hoody.com/api/v1/subserver-subscriptions/quote?plan_id=$PLAN_ID®ion=$REGION" \ -H "Authorization: Bearer $HOODY_TOKEN"
# 3. Buy it there with the quote's charge_cents as CHARGE_CENTS. Same key# rules as any purchase: resend with the same key after no answer; after# a refusal, unset BUY_KEY for a new key. Unset this key after the# operation is resolved and before starting another operation of the same kind.BUY_KEY="${BUY_KEY:-buy-$(date +%s)}"echo "idempotency key: $BUY_KEY"curl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/subserver-subscriptions" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"plan_id": "'"$PLAN_ID"'", "region": "'"$REGION"'", "idempotency_key": "'"$BUY_KEY"'", "max_charge_cents": '"$CHARGE_CENTS"'}'Then follow the purchase’s operation as in Buy a paid subserver. The subscription’s region shows where the subserver is (subscription fields), and so do the server’s own country, region and city once it is delivered.
Buy a paid subserver
Section titled “Buy a paid subserver”In the Hub:
- Go to Account > Plans & Billing > Plans and set Plans for to A new server.
- Choose the plan you want, for example Choose Plus.
- Under Location, keep Automatic (best available) or choose a place from the list. A place marked Full cannot be chosen. The location cannot be changed later.
- Check the plan, charge and balance, accept the terms and choose Confirm purchase.
- The subserver appears under Computers > Servers in the Subservers group and turns active once delivered. Its location is shown under its name in Account > Plans & Billing > Wallet & usage > Server subscriptions.
Through the API, the purchase answers 202 with an operation; the subscription starts in provisioning, with server_id null. Poll the operation: at succeeded the subscription is active with its server_id; at failed, read the subscription’s state: it shows delivery_failed or change_stuck. Contact support with the subscription ID.
Deploy computers on it
Section titled “Deploy computers on it”Once the subscription is active, create computers with its server_id as the server. A paid subserver is not in hoody servers list, which lists rentals.
In the Hub, open Computers, choose Get a computer, select your paid subserver under Server, choose the Project, set the Name, then choose Get computer.
# The subserver's ID is server_id on the subscriptionhoody servers subscriptions list -o json
hoody computers create --project "$PROJECT_ID" \ --server-id "$SUBSERVER_ID" \ --name "app" \ --hoody-kitimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const projectId = process.env.PROJECT_ID!;
const subs = await client.api.servers.subscriptions.list();const serverId = subs.data.find((sub) => sub.state === 'active' && sub.server_id)?.server_id;if (!serverId) throw new Error('No active subserver is available');
await client.api.computers.create(projectId, { name: 'app', server_id: serverId, hoody_kit: true });curl "https://api.hoody.com/api/v1/subserver-subscriptions" \ -H "Authorization: Bearer $HOODY_TOKEN"
curl -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/computers" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "app", "server_id": "'"$SUBSERVER_ID"'", "hoody_kit": true}'While the subscription is not active, and for new computers and copies while a renewal is pending, calls that change its computers return SUBSERVER_DORMANT (states).
Upgrade a paid subserver
Section titled “Upgrade a paid subserver”An upgrade moves the subscription to a plan that keeps or raises every resource and limit, and the AI tier (upgrade rules). An AI allowance the new plan sets below the one you have now is refused with ai_allowance in lower_fields. If lower_fields includes ai_allowance, choose another plan or contact support. It charges only the price difference for the rest of the current paid period; the renewal date stays, and renewals then charge the new price. The subserver stays in its region.
Its computers stop, it is resized in place, and each computer returns to the state it had before: a running computer starts again, a stopped one stays stopped. IDs and data stay the same. Plan a quiet moment.
In the Hub, go to Account > Plans & Billing > Wallet & usage, choose Upgrade on the subserver’s row under Server subscriptions, pick the bigger plan, review the charge, tick the checkbox that says you understand the purchase is not eligible for a customer-requested refund and agree to the Terms of Service and Privacy Policy, then choose Upgrade and pay.
set -eo pipefail
hoody servers subscriptions quote "$SUBSCRIPTION_ID" --action upgrade --plan-id "$NEW_PLAN_ID" -o json
# CHARGE_CENTS is the quote's charge_cents. The key is kept in UPGRADE_KEY,# or made once and printed: resend with it after no answer; after a refusal,# unset UPGRADE_KEY for a new key. Unset this key after the operation is# resolved and before starting another operation of the same kind.# Prompts before charging.UPGRADE_KEY="${UPGRADE_KEY:-upgrade-$(date +%s)}"echo "idempotency key: $UPGRADE_KEY"hoody servers subscriptions upgrade "$SUBSCRIPTION_ID" \ --plan-id "$NEW_PLAN_ID" \ --idempotency-key "$UPGRADE_KEY" \ --max-charge-cents "$CHARGE_CENTS"# Non-interactive (agents, CI): add -y to skip the prompt.import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const subscriptionId = process.env.SUBSCRIPTION_ID!;const newPlanId = process.env.NEW_PLAN_ID!;
const quote = await client.api.servers.subscriptions.quote(subscriptionId, { action: 'upgrade', plan_id: newPlanId });
// Keep the key: a resend after no answer reuses it and is charged once.// After a refusal, a retry needs a new key. Unset this key after the operation// is resolved and before starting another operation of the same kind.const idempotencyKey = process.env.UPGRADE_KEY ?? crypto.randomUUID();console.log('idempotency key:', idempotencyKey);await client.api.servers.subscriptions.upgrade(subscriptionId, { plan_id: newPlanId, idempotency_key: idempotencyKey, max_charge_cents: quote.data.charge_cents,});set -eo pipefail
curl -fsS "https://api.hoody.com/api/v1/subserver-subscriptions/$SUBSCRIPTION_ID/quote?action=upgrade&plan_id=$NEW_PLAN_ID" \ -H "Authorization: Bearer $HOODY_TOKEN"
# CHARGE_CENTS is the quote's charge_cents. Resend with the same key after no# answer; after a refusal, unset UPGRADE_KEY for a new key. Unset this key# after the operation is resolved and before starting another operation of# the same kind.UPGRADE_KEY="${UPGRADE_KEY:-upgrade-$(date +%s)}"echo "idempotency key: $UPGRADE_KEY"curl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/subserver-subscriptions/$SUBSCRIPTION_ID/upgrade" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"plan_id": "'"$NEW_PLAN_ID"'", "idempotency_key": "'"$UPGRADE_KEY"'", "max_charge_cents": '"$CHARGE_CENTS"'}'Follow the operation with hoody servers jobs get <operation-id>. If it fails, read the subscription. It may be active on the old plan or in change_stuck. Contact support with the operation ID about the state and charge.
There is no downgrade. To go smaller, buy a subserver on the smaller plan, move your computers to it with a cross-server copy, then cancel the bigger one.
Renewal and auto-renew
Section titled “Renewal and auto-renew”A subscription renews each calendar month on its renewal day (anchor_day). Initially this is the day you bought it; a late payment moves it to the payment day. In a month without that day, the period ends on its last day. Auto-renew is on from purchase: shortly before each period ends, Hoody charges the month’s price, Referral credit first, then General Balance, and moves paid_through a month ahead. The new period still starts when the current one ends. If the balance does not cover it, nothing is charged until the period ends. Hoody notifies you before each renewal, including when your balance will not cover it.
Turn auto-renew off or on at any time while the subscription is open, at no charge, with the Auto-renew switch on its row under Account > Plans & Billing > Wallet & usage > Server subscriptions in the Hub, or the CLI. Once it is being deleted (wiping) or closed (terminated), the switch is refused with 409 SUBSCRIPTION_NOT_PAYABLE. In the CLI:
hoody servers subscriptions autorenew disable "$SUBSCRIPTION_ID" -yhoody servers subscriptions autorenew enable "$SUBSCRIPTION_ID" -yHold and permanent deletion
Section titled “Hold and permanent deletion”A period that ends without renewal (auto-renew off, or too little balance) puts the subserver on hold:
- Its computers stop; their data stays for your plan version’s
hold_days, until the subscription’sdelete_at. Hoody notifies you before. - Paying during the hold charges a month and starts the subserver again; months on hold are never charged (late payment).
- When the hold ends unpaid, the subserver and every computer and snapshot on it are permanently deleted. Once deletion has begun (state
wiping), the subscription can no longer be paid and nothing can be recovered.
In the Hub, go to Account > Plans & Billing > Wallet & usage, choose Pay now on the held subserver under Server subscriptions, review the charge, tick the checkbox that says you understand the purchase is not eligible for a customer-requested refund and agree to the Terms of Service and Privacy Policy, then choose Confirm payment.
With the CLI or API, quote, then pay:
set -eo pipefail
hoody servers subscriptions quote "$SUBSCRIPTION_ID" --action pay -o json
# CHARGE_CENTS is the quote's charge_cents. The key is kept in PAY_KEY,# or made once and printed: resend with it after no answer; after a refusal,# unset PAY_KEY for a new key. Unset this key after the operation is# resolved and before starting another operation of the same kind.# Prompts before charging.PAY_KEY="${PAY_KEY:-pay-$(date +%s)}"echo "idempotency key: $PAY_KEY"hoody servers subscriptions pay "$SUBSCRIPTION_ID" \ --idempotency-key "$PAY_KEY" \ --max-charge-cents "$CHARGE_CENTS"# Non-interactive (agents, CI): add -y to skip the prompt.set -eo pipefail
curl -fsS "https://api.hoody.com/api/v1/subserver-subscriptions/$SUBSCRIPTION_ID/quote?action=pay" \ -H "Authorization: Bearer $HOODY_TOKEN"
# CHARGE_CENTS is the quote's charge_cents. Resend with the same key after no# answer; after a refusal, unset PAY_KEY for a new key. Unset this key# after the operation is resolved and before starting another operation of# the same kind.PAY_KEY="${PAY_KEY:-pay-$(date +%s)}"echo "idempotency key: $PAY_KEY"curl --fail-with-body -sS -X POST "https://api.hoody.com/api/v1/subserver-subscriptions/$SUBSCRIPTION_ID/pay" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"idempotency_key": "'"$PAY_KEY"'", "max_charge_cents": '"$CHARGE_CENTS"'}'Follow the operation the same way. If the resume fails, read the subscription’s state: it is held or change_stuck. A free retry is available when a fresh pay quote returns recovery: true and charge_cents 0: pay again with a new key. Contact support for change_stuck.
Cancel a paid subserver
Section titled “Cancel a paid subserver”Cancelling turns auto-renew off, with no refund of the current period. The subserver runs until paid_through, then goes on hold and is deleted if the hold ends unpaid. To keep computers, copy them to another server before paid_through. If a purchase was charged but not delivered, contact support.
In the Hub, cancel by turning off Auto-renew on its row and choosing Turn off auto-renew.
hoody servers subscriptions cancel "$SUBSCRIPTION_ID" -yAdvanced
Section titled “Advanced”- Scripts and agents: an auth token can buy and change subscriptions with the permissions in who can buy.
- One subscription:
hoody servers subscriptions get <subscription-id>shows its state,paid_throughanddelete_at(subscription fields). - Other languages:
--locale fr(or?locale=fr) on the plan list and subscription reads translates plan text (paid subserver plans on the Servers API page). - AI tier: a plan’s
ai_tieris its Hoody AI tier, and some AI models may be limited to tiers (plan limits).
Reference
Section titled “Reference”Tables and troubleshooting: the Paid Subservers reference.
What’s Next
Section titled “What’s Next”- Pricing: what Free, Plus and Pro include
- Manage Your Servers: free, paid and rented servers
- Billing & Payments: add funds to your General Balance
- Copy & Sync: move computers between servers