# Paid Subservers **Page:** foundation/servers/paid-subservers [Download Raw Markdown](./foundation/servers/paid-subservers.md) --- # 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](/foundation/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](/foundation/computers/copy-sync/#cross-server-copy), then delete the originals. Buying charges the first month at once: available [Referral credit](/foundation/wallet/referral-program/) first, then your General Balance ([add funds](/foundation/billing/)). Pass the quoted amount as `max_charge_cents` and an `idempotency_key` you generate: resending the same key returns the original purchase and charges nothing more. After a refusal, use a new key. ```bash set -eo pipefail # 1. List the plans and pick a plan version ID hoody servers plans list # 2. Quote it: check available, and set CHARGE_CENTS to the quote's charge_cents hoody 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 in the JSON buy answer) # Do not rerun this block to check on it: without BUY_KEY it buys again. ``` ```typescript 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' ``` ```bash set -eo pipefail # 1. List the plans curl -fsS "https://api.hoody.com/api/v1/subserver-plans" \ -H "Authorization: Bearer $HOODY_TOKEN" # 2. Quote one plan version curl -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/ # (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 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](/foundation/servers/paid-subservers/reference/#plan-limits)). 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](/foundation/hoody-api/realms/#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](/foundation/servers/rent/). [Virtual machines (KVM)](/foundation/servers/virtual-machines/) and [server commands](/foundation/servers/#server-commands) need a whole machine and are not available here. ## 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](#upgrade-a-paid-subserver) 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](/foundation/servers/paid-subservers/reference/#quote-fields)). ## 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](#in-the-account-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](/foundation/computers/copy-sync/#cross-server-copy), then cancel the old one. ```bash set -eo pipefail # 1. List the regions for the plan, and set REGION to an available one's region code hoody servers plans regions "$PLAN_ID" -o json # 2. Quote the plan there: check available, and set CHARGE_CENTS to charge_cents hoody 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. ``` ```typescript 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 } ``` ```bash set -eo pipefail # 1. List the regions for the plan curl -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](#delivery). The subscription's `region` shows where the subserver is ([subscription fields](/foundation/servers/paid-subservers/reference/#subscription-fields)), and so do the server's own `country`, `region` and `city` once it is delivered. ## Buy a paid subserver In the Hub: 1. Go to **Account > Plans & Billing > Plans** and set **Plans for** to **A new server**. 2. Choose the plan you want, for example **Choose Plus**. 3. 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. 4. Check the plan, charge and balance, accept the terms and choose **Confirm purchase**. 5. 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 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**. ```bash # The subserver's ID is server_id on the subscription hoody servers subscriptions list -o json hoody computers create --project "$PROJECT_ID" \ --server-id "$SUBSERVER_ID" \ --name "app" \ --hoody-kit ``` ```typescript import { 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 }); ``` ```bash 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](/foundation/servers/paid-subservers/reference/#subscription-states)). ## 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](/foundation/servers/paid-subservers/reference/#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](#choose-a-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**. ```bash 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. ``` ```typescript 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, }); ``` ```bash 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 `. 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](/foundation/computers/copy-sync/#cross-server-copy), then cancel the bigger one. ## 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: ```bash hoody servers subscriptions autorenew disable "$SUBSCRIPTION_ID" -y hoody servers subscriptions autorenew enable "$SUBSCRIPTION_ID" -y ``` ## Hold and permanent deletion When its hold ends, a held subserver is deleted with everything on it, and its computers cannot be copied while held. Only paying (**Pay now** in the Hub, or `pay`) keeps the data. Keep auto-renew on and a month's price on hand. A period that ends without renewal (auto-renew off, or too little balance) puts the subserver on hold: 1. Its computers stop; their data stays for your plan version's `hold_days`, until the subscription's `delete_at`. Hoody notifies you before. 2. Paying during the hold charges a month and starts the subserver again; months on hold are never charged ([late payment](/foundation/servers/paid-subservers/reference/#charges-and-retries)). 3. 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: ```bash 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. ``` ```bash 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 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**. ```bash hoody servers subscriptions cancel "$SUBSCRIPTION_ID" -y ``` ## Advanced - **Scripts and agents:** an [auth token](/foundation/hoody-api/authentication/) can buy and change subscriptions with the permissions in [who can buy](/foundation/servers/paid-subservers/reference/#who-can-buy). - **One subscription:** `hoody servers subscriptions get ` shows its state, `paid_through` and `delete_at` ([subscription fields](/foundation/servers/paid-subservers/reference/#subscription-fields)). - **Other languages:** `--locale fr` (or `?locale=fr`) on the plan list and subscription reads translates plan text ([paid subserver plans](/api/servers/#paid-subserver-plans) on the Servers API page). - **AI tier:** a plan's `ai_tier` is its Hoody AI tier, and some AI models may be limited to tiers ([plan limits](/foundation/servers/paid-subservers/reference/#plan-limits)). ## Reference Tables and troubleshooting: the [Paid Subservers reference](/foundation/servers/paid-subservers/reference/). ## What's Next - [Pricing](/foundation/pricing/): what Free, Plus and Pro include - [Manage Your Servers](/foundation/servers/): free, paid and rented servers - [Billing & Payments](/foundation/billing/): add funds to your General Balance - [Copy & Sync](/foundation/computers/copy-sync/): move computers between servers