Developers

Developer docs
Everything you need to wire ReferBeam in.

Most programs only need the snippet and a billing connection. The API, webhooks and MCP are there when you want more.

Install the snippet

Add this to the <head> of your marketing site and app. It stores a first-party visitor id so ReferBeam knows which partner sent each visitor. Your workspace slug is on the Install page in the dashboard.

HTML

<script src="https://referbeam.com/t.js" data-workspace="your-slug" data-cookie-days="60" defer></script>

Partner links look like https://referbeam.com/r/ethan-4k2p, or yoursite.com/?ref=ethan-4k2p on your own domain (the parameter is configurable in Settings › Tracking). Read the visitor id with window.ReferBeam.visitorId() and save it when someone signs up.

Send conversions

If you don't use a supported billing provider, tell ReferBeam about signups, payments and refunds from your server. Amounts are in cents: 0 records a signup, a negative amount is a refund. event_id makes the call idempotent.

cURL

curl -X POST https://referbeam.com/api/v1/conversions \
  -H "Authorization: Bearer $REFERBEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "in_1042",
    "customer": "cus_42",
    "amount": 4900,
    "currency": "USD",
    "visitor_id": "VISITOR_ID_SAVED_AT_SIGNUP",
    "interval": "month",
    "product_id": "pro"
  }'

The response status is recorded, signup, duplicate or unattributed. Optional fields — partner_code (a link or promo code), tax, billing_type, quantity, customer_email — feed commission flow conditions and reports.

Billing integrations

Connect Stripe with a restricted key, or paste the webhook URL and secret ReferBeam gives you into Paddle, Chargebee or RevenueCat. Payments create commissions, refunds reverse them and subscription changes keep each customer's status current.

To attribute a Stripe Checkout, pass the visitor id as client_reference_id. For RevenueCat, set the subscriber attribute referbeam_vid (or referbeam_code). See Integrations.

REST API

Authenticate with your workspace key (rk_live_…, from Install) as a Bearer token. Responses are JSON, money is integer cents with a currency, and lists page with cursor / next_cursor.

Method	Path	What it does
GET	/api/v1/me	Check your key; returns the workspace name.
GET	/api/v1/partners	List partners. Filters: status, limit (1–100), cursor.
POST	/api/v1/partners	Create a partner: name, email, optional coupon_code.
GET	/api/v1/partners/{id}	One partner with clicks, referrals and commission totals.
GET	/api/v1/commissions	List commissions. Filters: status, partner_id, since, cursor.
GET	/api/v1/referrals	List referred customers.
POST	/api/v1/conversions	Record a signup, payment or refund.
POST	/api/v1/hooks	Subscribe a URL to an event (Zapier/Make REST hooks).
DELETE	/api/v1/hooks/{id}	Unsubscribe.

Webhooks

Add an endpoint in Settings › Webhooks (or subscribe through /api/v1/hooks). ReferBeam sends { id, type, created, data } for events such as partner.created, partner.approved, referral.created, commission.created and payout.paid, and retries failures.

Every request is signed. Verify the ReferBeam-Signature header before trusting the body:

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

MCP for AI tools

ReferBeam runs a read-only MCP server, so Claude, ChatGPT, Cursor and other MCP clients can answer questions from your live program data.

Claude Code

claude mcp add --transport http referbeam https://referbeam.com/api/mcp \
  --header "Authorization: Bearer $REFERBEAM_API_KEY"

Tools include program stats, partner lists, top partners, the review queue and payout balances.