Build a referral program with Claude Code
A guided first integration: inspect your app, prepare a Program for human review, then connect a referral arrival to a real signup.
RefRef technical guide · Reviewed against source and official client documentation on 3 October 2026 · Review preview
Prerequisites
- Claude Code installed and authenticated, plus a local checkout of your application.
- Access to a configured RefRef environment and its MCP URL, including the /mcp path. Confirm the endpoint with your operator; this preview does not certify a public endpoint.
- A Console account with Workspace owner/admin authority for configuration, and an explicitly selected Sandbox Project.
- An application backend, stable user IDs, and an HTTPS test origin. Configure backend credentials outside the chat using the application integration reference.
Keep the MCP setup reference and application integration contract open. Configuration and runtime tracking are separate steps.
1. Connect in your application directory
Local scope keeps this server registration specific to this checkout. Set REFREF_MCP_URL to the endpoint supplied by your operator before running these commands. Complete OAuth in the browser; a Workspace API key is not an MCP credential.
claude mcp add --scope local --transport http refref "$REFREF_MCP_URL"
claude mcp login refref
claude mcp get refref2. Discover before configuring
Start Claude Code in the checkout. Use /mcp to inspect the connection. Paste this prompt and replace the bracketed values after discovery. A readable Project is not necessarily the intended Project.
Use RefRef get_workflow with workflow="configuration", then list_workspaces. Ask me to select the Workspace. List its Projects and show each environment. Use only the Sandbox Project I confirm. Read its current Programs and rules. For [program name], explain the minimum configuration needed to reward a signup. Do not assume a currency, amount, beneficiary, or attribution policy. Ask for missing choices. Prepare preview_change only after those choices are explicit. Return the exact changes and reviewUrl; do not approve or execute.3. Review the exact proposal
Open the returned Console review URL yourself. Check the Workspace, Sandbox environment, Program and benefit terms. Approve only the intended record. Then ask Claude Code to execute that approved proposal. If the state changed or the approval expired, request a new preview. A Program alone may still need policy, rules and published terms before it can be used.
4. Implement the signup boundary
Give Claude Code the canonical application integration reference linked below. Ask for one working signup path before adding purchases. This is application code work, separate from the MCP configuration step.
Inspect this app’s signup handler, session model and backend routes. Use the RefRef application integration reference I provide. Implement same-origin POST /refref/capture with a server-owned signed HttpOnly context cookie. Await window.RefRefAttribution.capture() before signup. Use the authenticated app user ID as an individual participant externalId. Preserve the first evidence snapshot for retries. Keep API keys and Project signing secrets server-only. Show the changed files and run focused tests for successful capture, failed capture and repeated signup delivery. Do not invent endpoints or claim money was delivered.5. Walk two people through it
Enroll test participant A in the referral Program and obtain A’s sharing link. In a separate browser session, open that link and sign up as B. Inspect the accepted signup and the preserved referral in RefRef. Compare IDs, not email addresses. Use the checks below before calling the integration ready.
A concrete signup example
Use these disposable identities in your Sandbox test. These are expected outcomes under a policy that qualifies A’s touch, not recorded production results.
01
Referrer: user-a
Enroll individual user-a in the selected referral Program and create their sharing code. Keep that code for repeat visits.
02
Arrival: user-b
Open A’s link in a separate browser session. Complete capture before submitting B’s signup. B’s identity comes from your backend signup result.
03
Inspect one relationship
Use the accepted signup’s Event ID to diagnose processing. The completed qualifying referral must name user-a as referrer and user-b as referee; signup acceptance alone is insufficient.
Record actual results beside these checks
- CHECK 01Ask the connected client to list the selected Workspace’s Projects.
- Expected resultThe chosen Project ID and Sandbox environment are explicit.
- CHECK 02Try to execute an unapproved disposable proposal.
- Expected resultExecution is rejected; no configuration mutation occurs.
- CHECK 03Follow A’s link and sign up as B after successful capture.
- Expected resultThe accepted signup resolves B; the preserved referral names A as referrer and B as referee when the configured attribution policy qualifies the touch.
- CHECK 04Fail capture, then retry the same signup delivery after recovery.
- Expected resultFailed capture blocks submission. Repeated delivery with the original business facts and evidence does not create another Event or Reward.
An earned Reward is an accounting result. It does not establish that cash, credit or a discount was delivered.
What has actually been validated
RefRef’s repository status records real Claude Code CLI OAuth, discovery, Sandbox/Live reads, preview and pre-approval rejection checks against disposable local fixtures. During this guide review, installed CLI help confirmed add/login/get commands. The full application journey described here was not rerun, and hosted readiness is not established.