Referral Program reference
Section titled “Referral Program reference”Lookup tables for the Referral Program. Every route and response is also in the Wallet API.
Access and limits
Section titled “Access and limits”| Route | What it does | Credential |
|---|---|---|
GET /api/v1/referrals/me | Your program status: codes, level, counts and credit totals | A 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/me | Join the program and receive your first code | Signed-in session only |
POST /api/v1/referrals/me/codes | Create a vanity code | Signed-in session only |
DELETE /api/v1/referrals/me/codes/{code} | Release a vanity code for good | Signed-in session only |
GET /api/v1/referrals/me/codes/check?code= | Check whether a code is allowed and free | Signed-in session only |
| Topic | Rule |
|---|---|
| Auth tokens | Refused with 403 on every route marked signed-in session only |
| HTTP Basic | Refused on every referral route |
| Rate limit | All 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 |
| CLI | hoody referrals get, hoody referrals join, and hoody referrals codes check, create or release with the code as argument |
| SDK | client.api.referrals.get(), .join(), .codes.check({ code }), .codes.create({ code }) and .codes.release(code) |
| MCP | An 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 |
Eligibility
Section titled “Eligibility”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?.
| Case | Effect |
|---|---|
| You refund your last qualifying purchase | Can withdraw your eligibility. It comes back with your next qualifying purchase |
| A payment is disputed | Hoody 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 rental | Made eligible through a one-time grant. Getting a server later does not make an account eligible by itself |
| Purchases made before the program opened | Checked against your purchase history. If eligible is false and you think it should be true, contact support |
Code rules
Section titled “Code rules”| Rule | Value |
|---|---|
| Random code | 8 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 format | 4 to 20 characters: lowercase letters, digits, and single hyphens between them (no hyphen at the start or end) |
| Letter case | Uppercase is accepted and stored in lowercase, so Alex-Builds becomes alex-builds |
| Refused words | Words 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 code | Hoody may block a code that breaks these rules. A blocked code stops working, and its link is null |
| Checking a code | Works only once you have joined |
| How long a link lasts | As 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 shape | Share https://hoody.com/signup?ref=<code> so the signup page remembers your code. Alternatively, ask the person to enter it in Referral code (optional) |
Signup capture
Section titled “Signup capture”| Situation | What happens |
|---|---|
| Several referral links opened | The first one is kept |
| Link opened while someone is signed in on that browser | Not remembered |
| Sign up without a referral | Clear the Referral code (optional) field |
| After an email signup succeeds | The 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 forgotten | Once someone signs in on that browser, or after its 7 days |
| Code owner no longer eligible, or has left the program | The account is created as usual, without a referrer |
| Question about the signup’s validity | The 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 API | Code | Source |
|---|---|---|
| Email signup | referral_code in the request body | Optional referral_source, link or typed |
| Public browser GitHub or Google sign-in | ref query parameter on its start URL | Optional 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.
Levels
Section titled “Levels”| Rule | Detail |
|---|---|
| Month of a purchase | Each purchase earns at the level of the calendar month, in UTC, in which it is activated |
| Who counts | A customer counts as long as not all of their credit was reversed, also after their 12-month earning window has ended |
| Current month | Its 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 Creator | Only 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.
Qualifying spend
Section titled “Qualifying spend”| Rule | Detail |
|---|---|
| Hoody AI | Hoody AI credit does not earn |
| Setup fees | Do 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 |
| Rounding | Credit 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 |
Earning window
Section titled “Earning window”| Rule | Detail |
|---|---|
| What earns | Only 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 purchase | A 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 metal | The 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, refunds | Do not restart the 3 months |
| Prepaid bare metal | Earns 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 |
Credit hold and reversals
Section titled “Credit hold and reversals”| Rule | Detail |
|---|---|
| Release | Credit 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 pays | First any referral_credit_owed; the rest goes to your Referral credit balance |
| New paying customer | A new paying customer and its pending credit can take a little while to show in your totals |
| Disputed or provider-refunded payment | If 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 purchase | The credit it earned is reduced or reversed automatically |
| Review | Hoody may review referral credit and hold or reverse it under the program rules |
Referral credit rules
Section titled “Referral credit rules”| Rule | Detail |
|---|---|
| Spend order | Referral 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 purchases | Each 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 read | GET /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 history | A 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” |
| Invoices | An invoice paid partly with this credit shows it on a separate “Referral credit” line |
| Owed credit | referral_credit_owed stays until future referral earnings cover it |
| Deleting your account | Also discards anything owed, and releases your codes |
| A referred customer deletes their account | Credit already earned from their purchases is still released to you |
| Below Creator | Referrers use their credit for servers only |
Status fields
Section titled “Status fields”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" }}| Field | Meaning |
|---|---|
eligible | Whether 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 |
state | active or removed once you have joined, null before |
codes | Your 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_left | How many vanity codes you can create right now; 0 whenever creating one would be refused |
counts.signed_up | People who signed up with one of your codes, not counting self-referrals and dropped referrals |
counts.paying | Of those, people who have made a qualifying payment |
counts.active | Referred 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_customers | Your 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.pending | Earned credit not released yet: in its 60-day hold, or delayed by processing or a review |
credit.available | Your 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.reversed | Credit reversed after refunds or a review |
credit.owed | Credit reversed after you spent it; new Referral credit repays it first |
monthly | Credit 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_at | The 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.
Privacy
Section titled “Privacy”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.
Program changes and review
Section titled “Program changes and review”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 program | Effect |
|---|---|
| Codes | Stay listed with a null link and stop bringing in signups |
| Credit on hold | Stays 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 eligible | Never earn credit, even if your account is restored later |
| Losing eligibility on its own | Does not stop credit already on hold from being released |
Errors
Section titled “Errors”| HTTP | Code | Meaning | What to do |
|---|---|---|---|
| 400 | REFERRAL_CODE_INVALID | Length or characters break the format rules | See Code rules |
| 400 | REFERRAL_CODE_RESERVED | The code contains a word that is not allowed | Choose another code |
| 403 | AFFILIATE_NOT_ELIGIBLE | Your account is not eligible for the program right now | See Troubleshooting |
| 403 | AFFILIATE_REMOVED | Your account is no longer part of the program, so it cannot join again or create codes | Contact support if you have questions about it |
| 403 | REFERRAL_CODE_ISSUANCE_BLOCKED | Your account cannot create new codes | |
| 404 | AFFILIATE_NOT_ENROLLED | You have not joined | Join the program first |
| 404 | REFERRAL_CODE_NOT_FOUND | Release: the code does not exist or is not one of your codes | Check the spelling against the codes list in GET /api/v1/referrals/me |
| 409 | AFFILIATE_ENROLMENT_PAUSED | Join: new enrolment is paused | Check enrolment_open in GET /api/v1/referrals/me and try again later |
| 409 | AFFILIATE_ALREADY_ENROLLED | Join: your account is already in the program | Read your codes and totals with GET /api/v1/referrals/me |
| 409 | REFERRAL_CODE_TAKEN | The code exists already, or was used before | Choose another code |
| 409 | REFERRAL_CODE_LIMIT_REACHED | You already have 3 active vanity codes, or have created 10 | |
| 409 | REFERRAL_CODE_NOT_REMOVABLE | Release: your random code cannot be released, and neither can a blocked code or one already released | Only active vanity codes can be released |
| 422 | Validation error | Create: 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 | |
| 429 | Rate limited | Too many referral requests | Wait 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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
Joining returns AFFILIATE_NOT_ELIGIBLE | Your account does not yet have an activated plan purchase paid at least partly by card or crypto, or its eligibility was withdrawn | If 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 counts | One 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 capture | None for banding. A referral cannot be added to an existing account later |