# Referral Program reference **Page:** foundation/wallet/referral-program/reference [Download Raw Markdown](./foundation/wallet/referral-program/reference.md) --- # Referral Program reference Lookup tables for the [Referral Program](/foundation/wallet/referral-program/). Every route and response is also in the [Wallet API](/api/wallet/). ## 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](/foundation/hoody-api/authentication/) 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 `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?](/foundation/wallet/referral-program/#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 | 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=` so the signup page remembers your code. Alternatively, ask the person to enter it in **Referral code (optional)** | ## 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 | 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 | 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 | 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 | 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 | 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 `GET /api/v1/referrals/me` returns your program status, codes, level and credit totals: ```json { "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](#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](#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 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 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 | HTTP | Code | Meaning | What to do | |---|---|---|---| | 400 | `REFERRAL_CODE_INVALID` | Length or characters break the format rules | See [Code rules](#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](#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 | 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](/foundation/servers/paid-subservers/) or [rent a server](/foundation/servers/rent/), 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](#signup-capture) | None for banding. A referral cannot be added to an existing account later |