Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for the Referral Program. Every route and response is also in the Wallet API.

RouteWhat it doesCredential
GET /api/v1/referrals/meYour program status: codes, level, counts and credit totalsA signed-in session, or an auth token that has the financial.wallet.read permission and is not limited to realms. An auth token limited to realms is refused with 403 INSUFFICIENT_PERMISSIONS
POST /api/v1/referrals/meJoin the program and receive your first codeSigned-in session only
POST /api/v1/referrals/me/codesCreate a vanity codeSigned-in session only
DELETE /api/v1/referrals/me/codes/{code}Release a vanity code for goodSigned-in session only
GET /api/v1/referrals/me/codes/check?code=Check whether a code is allowed and freeSigned-in session only
TopicRule
Auth tokensRefused with 403 on every route marked signed-in session only
HTTP BasicRefused on every referral route
Rate limitAll referral requests are rate limited per account. Over the limit, the API answers 429 with a Retry-After header; wait that many seconds and try again
CLIhoody referrals get, hoody referrals join, and hoody referrals codes check, create or release with the code as argument
SDKclient.api.referrals.get(), .join(), .codes.check({ code }), .codes.create({ code }) and .codes.release(code)
MCPAn agent using MCP can read your referral status. Joining and creating, checking or releasing codes are not MCP tools: they need your own signed-in session

eligible in GET /api/v1/referrals/me says whether you can join, and enrolled says whether you already have. The basic rule is in Who can join?.

CaseEffect
You refund your last qualifying purchaseCan withdraw your eligibility. It comes back with your next qualifying purchase
A payment is disputedHoody reviews the account, and eligibility can be withdrawn after that review. Another purchase does not restore it; contact support if you think your account should be eligible
Some existing accounts, including accounts that had a free server or a rentalMade eligible through a one-time grant. Getting a server later does not make an account eligible by itself
Purchases made before the program openedChecked against your purchase history. If eligible is false and you think it should be true, contact support
RuleValue
Random code8 characters, leaving out 0, o, 1, l and i, so it is easy to type. It stays with your account and does not count toward the vanity code limits
Vanity code format4 to 20 characters: lowercase letters, digits, and single hyphens between them (no hyphen at the start or end)
Letter caseUppercase is accepted and stored in lowercase, so Alex-Builds becomes alex-builds
Refused wordsWords that could be mistaken for Hoody itself (such as hoody, admin, support, staff or official), words that read like a Hoody offer or the referral program itself, and offensive words
Blocked codeHoody may block a code that breaks these rules. A blocked code stops working, and its link is null
Checking a codeWorks only once you have joined
How long a link lastsAs long as its code is active and you are in the program and eligible. The browser remembers the code for 7 days after the link is opened; after that, the person can open the link again or type the code
Link shapeShare https://hoody.com/signup?ref=<code> so the signup page remembers your code. Alternatively, ask the person to enter it in Referral code (optional)
SituationWhat happens
Several referral links openedThe first one is kept
Link opened while someone is signed in on that browserNot remembered
Sign up without a referralClear the Referral code (optional) field
After an email signup succeedsThe browser remembers the code it used, including a typed one, so a retry or a later GitHub or Google sign-up keeps it. A typed code is remembered for 7 days from when it was first submitted
Remembered code forgottenOnce someone signs in on that browser, or after its 7 days
Code owner no longer eligible, or has left the programThe account is created as usual, without a referrer
Question about the signup’s validityThe referral may be dropped; one that already led to a qualifying purchase is kept. Nobody earns credit from an account whose referral was dropped
Signup over the APICodeSource
Email signupreferral_code in the request bodyOptional referral_source, link or typed
Public browser GitHub or Google sign-inref query parameter on its start URLOptional ref_source query parameter

The source defaults to link. The code may be at most 64 characters, and the source must be link or typed; a request that breaks either rule is refused with a 422 validation error, so the signup or sign-in does not start. Device authorization and application-launch sign-ins do not capture referral codes.

RuleDetail
Month of a purchaseEach purchase earns at the level of the calendar month, in UTC, in which it is activated
Who countsA customer counts as long as not all of their credit was reversed, also after their 12-month earning window has ended
Current monthIts level is a preview until the first qualifying purchase of that month is processed, and a reversal can still change it until then; after that, the level stays fixed for the month
Losing CreatorOnly if reversals bring the count back to 10 or fewer. You then earn 5% again from the next month whose level is not yet fixed, including the current month while its level is still a preview. Credit already earned is kept: a level change never reduces it

In GET /api/v1/referrals/me, level and rate_percent show your current level, creator_threshold_active_customers how many customers Creator needs, creator_rate_percent the Creator share, and creator_customers how many of your customers count for Creator today, counted the way next month’s level will be.

RuleDetail
Hoody AIHoody AI credit does not earn
Setup feesDo not earn. When a purchase with a setup fee is paid partly by card or crypto and partly with credit, the card or crypto part is split between the setup fee and the server time in proportion to their prices, and only the server-time share earns
RoundingCredit is calculated in whole cents, rounded down, so a very small purchase can earn nothing. It still counts as the customer’s first qualifying purchase
RuleDetail
What earnsOnly service within the 12-month window: a purchase whose service time runs past the end of the window earns only on the share inside it
First purchaseA first purchase with no service time inside the window it would start does not start the window. That purchase must be ordered within 90 days of signup; delivery can happen later
Bare metalThe customer’s first 3 months of bare-metal service are counted as calendar time from when their first bare-metal server starts, however that first server was paid for (free, with credit, or later refunded)
Gaps, extensions, refundsDo not restart the 3 months
Prepaid bare metalEarns only on the part of its service time that falls inside those 3 months, so a 12-month prepaid rental earns on roughly a quarter of its price
RuleDetail
ReleaseCredit becomes due at the first 00:00 UTC at or after the end of its hold, and all of your credit due by then is released together. More than one release can reach you on the same day
What a release paysFirst any referral_credit_owed; the rest goes to your Referral credit balance
New paying customerA new paying customer and its pending credit can take a little while to show in your totals
Disputed or provider-refunded paymentIf a referred customer’s card or crypto payment is disputed or refunded by the payment provider, credit from that customer stays on hold while Hoody reviews it, also past its release day. After the review it is released, reduced or reversed
Cancelled and refunded purchaseThe credit it earned is reduced or reversed automatically
ReviewHoody may review referral credit and hold or reverse it under the program rules
RuleDetail
Spend orderReferral credit is spent first on server purchases, with nothing to choose. After it, promotional balance is used before money you paid in
Refunds of your purchasesEach part returns to the balance that paid it; a partial refund is split in proportion to what is left of each part, in whole cents. Referral credit that comes back first covers any referral_credit_owed. A server purchase made before the program opened is refunded to your General Balance as promotional balance
Balance readGET /api/v1/wallet/balances returns it as referral_credit. An auth token limited to realms is refused on that call (403 REALM_TOKEN_ACCOUNT_MONEY), like every account balance read; use a signed-in session, the Hub or an account-wide token
Transaction historyA release that adds to your balance shows as “Referral reward” (a release used entirely to cover what you owe adds no entry). A reversal that reduces your balance shows as “Referral reward reversal”
InvoicesAn invoice paid partly with this credit shows it on a separate “Referral credit” line
Owed creditreferral_credit_owed stays until future referral earnings cover it
Deleting your accountAlso discards anything owed, and releases your codes
A referred customer deletes their accountCredit already earned from their purchases is still released to you
Below CreatorReferrers use their credit for servers only

GET /api/v1/referrals/me returns your program status, codes, level and credit totals:

{
"statusCode": 200,
"message": "Referral program status retrieved",
"data": {
"eligible": true,
"enrolled": true,
"state": "active",
"enrolment_open": true,
"level": "referrer",
"rate_percent": "5",
"creator_threshold_active_customers": 11,
"creator_rate_percent": "10",
"creator_customers": "fewer_than_3",
"codes": [
{
"code": "k7m2q9xa",
"kind": "random",
"state": "active",
"link": "https://hoody.com/r/k7m2q9xa"
}
],
"vanity_codes_left": 3,
"counts": { "signed_up": "fewer_than_3", "paying": "0", "active": "0" },
"credit": { "pending": "12.40", "available": "3.00", "reversed": "0.00", "owed": "0.00" },
"monthly": [{ "month": "2026-10", "earned": "4.20", "reversed": "0.00" }],
"next_release_at": "2026-12-24T00:00:00.000Z"
}
}
FieldMeaning
eligibleWhether your account meets the program’s eligibility rule. It does not change a removed state; vanity_codes_left shows whether you can create codes now
stateactive or removed once you have joined, null before
codesYour random code and your active and blocked vanity codes. link is null for a blocked code, and for every code once your account has left the program
vanity_codes_leftHow many vanity codes you can create right now; 0 whenever creating one would be refused
counts.signed_upPeople who signed up with one of your codes, not counting self-referrals and dropped referrals
counts.payingOf those, people who have made a qualifying payment
counts.activeReferred customers who earned you credit, after reversals, this calendar month or last. This shows recent activity only; your level uses its own count, described in Levels
creator_customersYour customers who count for Creator, measured the way next month’s level will be: banded like the other counts (0, fewer_than_3 for one or two, else the exact number). It counts customers whose credit was activated before next month begins; next month’s level is then fixed as described in Levels
credit.pendingEarned credit not released yet: in its 60-day hold, or delayed by processing or a review
credit.availableYour current spendable Referral credit balance, the same amount as referral_credit in GET /api/v1/wallet/balances. It goes down when you spend it
credit.reversedCredit reversed after refunds or a review
credit.owedCredit reversed after you spent it; new Referral credit repays it first
monthlyCredit earned and reversed, grouped by the UTC calendar month in which the referred purchase was activated, newest first. A later release or reversal stays in that purchase’s month. It covers the current month and the 11 before it, and lists only months with earnings; older months are never shown
next_release_atThe next release day, at 00:00 UTC, or null when no credit is due on a coming day; it can be null while credit is still pending. Processing or a review can delay the release itself

Amounts are dollar strings, as in the rest of the wallet.

The banded counts limit the information shared, but they do not guarantee anonymity. To run the program, Hoody keeps a record of which account referred which, along with the related purchase, payment and credit history. These records can remain after an account is deleted and follow the same retention rules as other financial records. Individual referral records are never shown to referrers.

The program is meant to reward people who bring real customers to Hoody. To keep it fair for everyone, Hoody may review referrals and credit, hold or reverse credit, remove codes, or end an account’s participation in the program. Hoody may also change the program’s rates and rules, or end the program.

If your account leaves the programEffect
CodesStay listed with a null link and stop bringing in signups
Credit on holdStays on hold while your account is out of the program; it is released if your account is restored, unless Hoody forfeits it
Purchases processed while out of the program or not eligibleNever earn credit, even if your account is restored later
Losing eligibility on its ownDoes not stop credit already on hold from being released
HTTPCodeMeaningWhat to do
400REFERRAL_CODE_INVALIDLength or characters break the format rulesSee Code rules
400REFERRAL_CODE_RESERVEDThe code contains a word that is not allowedChoose another code
403AFFILIATE_NOT_ELIGIBLEYour account is not eligible for the program right nowSee Troubleshooting
403AFFILIATE_REMOVEDYour account is no longer part of the program, so it cannot join again or create codesContact support if you have questions about it
403REFERRAL_CODE_ISSUANCE_BLOCKEDYour account cannot create new codes
404AFFILIATE_NOT_ENROLLEDYou have not joinedJoin the program first
404REFERRAL_CODE_NOT_FOUNDRelease: the code does not exist or is not one of your codesCheck the spelling against the codes list in GET /api/v1/referrals/me
409AFFILIATE_ENROLMENT_PAUSEDJoin: new enrolment is pausedCheck enrolment_open in GET /api/v1/referrals/me and try again later
409AFFILIATE_ALREADY_ENROLLEDJoin: your account is already in the programRead your codes and totals with GET /api/v1/referrals/me
409REFERRAL_CODE_TAKENThe code exists already, or was used beforeChoose another code
409REFERRAL_CODE_LIMIT_REACHEDYou already have 3 active vanity codes, or have created 10
409REFERRAL_CODE_NOT_REMOVABLERelease: your random code cannot be released, and neither can a blocked code or one already releasedOnly active vanity codes can be released
422Validation errorCreate: a body without a code string of 1 to 64 characters, before the checks above. Check: a missing, empty or longer code. Release: a value in the URL that cannot be a code at all (not 4 to 20 letters, digits and single hyphens), before it is looked up
429Rate limitedToo many referral requestsWait the Retry-After seconds

GET /api/v1/referrals/me/codes/check?code= tests a code first. For a code of 1 to 64 characters it answers 200 with code, valid, available and reason, which is REFERRAL_CODE_INVALID, REFERRAL_CODE_RESERVED, REFERRAL_CODE_TAKEN or null. When you could not create a code right now, the check answers with the same error as creating one would (for example AFFILIATE_NOT_ENROLLED or REFERRAL_CODE_LIMIT_REACHED), so a code it reports as available is one you can create.

SymptomCauseWhat to do
Joining returns AFFILIATE_NOT_ELIGIBLEYour account does not yet have an activated plan purchase paid at least partly by card or crypto, or its eligibility was withdrawnIf you have not made a qualifying purchase yet, buy a paid subserver or rent a server, wait for it to be activated, then try again. Right after activation, eligibility can take a little while to update: check eligible in GET /api/v1/referrals/me before retrying. Eligibility lost after a refund comes back with your next qualifying purchase. If Hoody withdrew it after a review, another purchase does not restore it; contact support if you think your account should be eligible
A signup did not show up in my countsOne more signup may not change a banded count ("0", "fewer_than_3"). A signup also does not count when it was made on an account that already existed, when the code was mistyped or no longer active, when your account was not eligible or not in the program at that moment, or when its referral was dropped as described in Signup captureNone for banding. A referral cannot be added to an existing account later