Referlist Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
-
What are you trying to do?
- A) Add a viral referral waitlist to a landing page — which of the 5 install methods (embedded form, npm SDK, JS snippet + element IDs, manual
addToWaitlist call, REST API)
- B) Integrate the npm SDK in a React/Next.js app (incl. the SSR
window workaround)
- C) Use the REST API (Pro+) — add signups, get an email's place in line, list the waitlist, attach a referral code
- D) Get signups out — export to Mailchimp / Airtable / CSV
- E) Set up referral mechanics — unique links, queue jumping, position display, seeding
- F) Pick a tier — Free (100) vs Growth $29 (500) vs Pro $59 (3,000, API) vs Enterprise (unlimited)
- G) Compare Referlist to Waitlister / GetWaitlist / LaunchList / Viral Loops
-
Where will the form live? Hosted Referlist page / a no-code builder (Webflow, Squarespace, Wix) / a React/Next.js app — drives embed vs SDK vs API.
-
Where do signups need to end up? Stay in Referlist / Mailchimp / Airtable / your own backend — drives export vs the Pro REST API.
Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.
Step 2 — Route or answer directly
| If the question is about... | Route to... |
|---|
| General audience/list-growth strategy across platforms | /sales-audience-growth [question] |
| A waitlist with built-in email broadcasts + HMAC-signed webhooks | /sales-waitlister [question] |
| A developer waitlist with an unauthenticated signup API + censored leaderboard | /sales-getwaitlist [question] |
| One-time-pricing waitlist (form POST + webhooks, no API) | /sales-launchlist [question] |
| Waitlists + giveaways/contests with fraud webhooks | /sales-kickofflabs [question] |
| Sending the actual launch/nurture campaign to the list | /sales-email-marketing [question] |
When routing, give the exact command, e.g.: "This is a list-growth-strategy question — run: /sales-audience-growth [your question]."
If the question is Referlist-specific, continue to Step 3.
Step 3 — Referlist platform reference
Read references/platform-guide.md for the full reference — the 5 install methods, capabilities tagged by automation surface, pricing and plan gates, referral/seeding mechanics, export integrations, quick-start recipes (Next.js SDK with SSR workaround; manual addToWaitlist with referral attribution; signups→Mailchimp), and a fit comparison vs Waitlister / GetWaitlist / LaunchList / Viral Loops.
Read references/referlist-api-reference.md for the programmatic surface — the client-side SDK (referlist.initialize({ domain }), element IDs referlistemail/referlistbutton, window.referlist.addToWaitlist(domain, email, referralCode)) verbatim, plus the Pro-gated REST API capabilities (add signup, get an email's place in line, list signups, referral code). The REST base URL, auth, and exact paths are not in the public docs index (docs.referlist.co is JS-rendered) — they're listed under ## Gaps to verify, not invented.
Answer the user's question using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
Focus on the user's specific situation:
- Pick the lightest install that fits. Pure no-code site → embedded form or JS snippet. React/Next.js → the npm SDK. Custom backend or server-side adds → the REST API (Pro only).
- The REST API is Pro-gated ($59/mo). Below Pro, programmatic access is the client-side SDK plus CSV/Mailchimp/Airtable export — there's no server-side read/write API on Free/Growth.
- Next.js SSR breaks the SDK unless you
dynamic(import, { ssr: false }) — the library touches window. This is the single most common integration failure.
- Referral attribution is your job to forward. Capture the visitor's referral code (from the URL) and pass it as the 3rd arg of
addToWaitlist (or let the snippet handle it) — omit it and the referrer never moves up.
- No confirmed webhooks/Zapier. Treat egress as API polling (Pro) or export (Mailchimp/Airtable/CSV). If you need push notifications, verify webhooks exist before designing around them — or use
/sales-waitlister / /sales-kickofflabs.
- Seed the list (Pro+) so a brand-new waitlist doesn't look empty, but keep seeds honest.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research (2026-06) — review these, especially plan-gated features and pricing that may shift. Referlist's docs site is JS-rendered, so REST API specifics below are flagged for verification.
- REST API is Pro-gated ($59/mo). Free and Growth have no server-side API — only the client-side SDK + export. Don't promise an API integration on a cheaper tier.
- Next.js "window is not defined". The SDK runs client-side; import it with
dynamic(() => import(...), { ssr: false }) or guard on typeof window !== 'undefined'.
- REST base URL / auth aren't in the public docs index. docs.referlist.co is a JS-rendered SPA; the SDK GitHub repo is client-side only (last updated 2022). Verify the base URL, auth header, and endpoint paths in the live (signed-in) docs before building — they are not documented in this skill, only the capabilities are.
- Referral code must be forwarded. Manual
addToWaitlist(domain, email, referralCode) calls that omit the code, or pages that don't capture the inbound ?ref param, record the signup but credit no one — so positions never move.
- Plan caps are on signups, and export is gated. Free = 100 signups, Growth = 500, Pro = 3,000, Enterprise = unlimited (usage-based ~$0.01/signup/mo). Collecting past your cap or exporting beyond Free's 100 needs an upgrade.
- Branded email-sending domain, waitlist seeding, and multi-language are Pro+. On Free/Growth, confirmation emails come from a Referlist domain and there's a watermark on Free.
- No confirmed webhooks or Zapier. Egress is the Pro REST API (poll) or CSV/Mailchimp/Airtable export. Verify before assuming real-time push exists.
- Pricing is best-effort. An older Product Hunt listing cited "$50/mo unlimited"; current public pricing is Growth $29 / Pro $59 / usage-based Enterprise. Re-check the live pricing page.
Related skills
/sales-audience-growth — List-growth strategy (lead magnets, referral design, cross-promotion across all platforms)/sales-waitlister — Waitlister (built-in email broadcasts, documented REST API + HMAC-signed webhooks)/sales-getwaitlist — GetWaitlist (developer widget, unauthenticated signup API, censored public leaderboard)/sales-launchlist — LaunchList (one-time-pricing waitlists, form POST + webhooks, no API)/sales-kickofflabs — KickoffLabs (waitlists + giveaways with REST API + fraud webhooks)/sales-email-marketing — Email marketing strategy (what to send once you have the list)/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: No-code viral waitlist on a Webflow landing page
User says: "I have a Webflow landing page and want a waitlist where people move up by referring friends, without writing code. How do I set it up with Referlist?"
Skill does: Recommends the embedded signup form or the JS-snippet method (add the snippet, then put id="referlistemail" on the email input and id="referlistbutton" on the button). Explains the visitor sees their place in line + a unique referral link, and each referred join moves them up. Notes Free covers 100 signups (Growth $29 for 500 + no watermark), and that confirmation emails come from a Referlist domain until Pro.
Result: User has a gamified referral waitlist live on Webflow with no code.
Example 2: React/Next.js SDK integration with referral attribution (developer/automation)
User says: "I'm adding Referlist to my Next.js app via the npm package but I get 'window is not defined', and when I call addToWaitlist manually nobody gets referral credit."
Skill does: Fixes the SSR error by loading the SDK with dynamic(() => import('referlist'), { ssr: false }) (or a useEffect mount guard), then calling referlist.initialize({ domain: 'YOUR_DOMAIN' }). For attribution, shows reading the inbound ?ref= code from the URL and passing it as the 3rd arg: window.referlist.addToWaitlist('YOUR_DOMAIN', email, referralCode) — omitting it is why no one moved up. Points to Recipe 1/2 in references/platform-guide.md.
Result: SDK initializes client-side and referral codes credit the right referrer.
Example 3: Tier choice + getting signups into Mailchimp
User says: "I expect ~2,000 signups and need them all in Mailchimp. Which Referlist plan, and how do I sync?"
Skill does: Recommends Pro ($59/mo, 3,000 signups) since Growth caps at 500; notes Pro also unlocks the REST API and branded email domains. For Mailchimp, points to the native export (CSV/Mailchimp/Airtable) for a one-shot/manual sync, or the Pro REST API to pull the list programmatically on a schedule. Hands off the launch broadcast itself to /sales-email-marketing.
Result: User picks Pro and has a path to keep Mailchimp in sync with the waitlist.
Troubleshooting
Next.js build/runtime fails with "window is not defined"
Symptom: Importing or initializing the Referlist SDK crashes during SSR/build.
Cause: The SDK accesses the browser window object and must run client-side.
Solution: Load it with dynamic(() => import('referlist'), { ssr: false }), or import inside a useEffect/componentDidMount that only runs in the browser, then call referlist.initialize({ domain: 'YOUR_DOMAIN' }). Don't import it at module top level in a server component.
Referrals aren't crediting / positions don't move
Symptom: People share their link and friends join, but no one moves up the queue and referral counts stay flat.
Cause: The referral code isn't being captured/forwarded — either the inbound ?ref param isn't read, or the manual addToWaitlist call omits the 3rd referralCode argument.
Solution: If using the auto element-ID method, confirm referlistemail/referlistbutton are set and the page is loaded with the referral URL. If calling the API manually, capture the referral code from the visitor's URL and pass it: window.referlist.addToWaitlist('YOUR_DOMAIN', email, referralCode). Verify in the dashboard that the referrer's position updates.
I can't export my signups (or hit a cap)
Symptom: Export is blocked, or you can't collect/export beyond a certain number.
Cause: Plan caps — Free is 100 signups and export beyond 100 is gated; Growth is 500; Pro is 3,000.
Solution: Upgrade to the tier that covers your volume (Growth $29 / Pro $59 / Enterprise usage-based), then export to CSV, Mailchimp, or Airtable. For ongoing programmatic sync, use the REST API on Pro rather than repeated manual exports.
