ReferralmeterDocs
Dashboard
All docs pages

Install

Server-side referrals

Report signups and sales from your server with a secret key.

Use these when signup completes on your server, or when you bill through something Referralmeter doesn't connect to natively. They take your secret key (sk_…) with the write scope. Never put it in browser code.

Record a signup

The server-side twin of referralmeter.signup(). referral is what referralmeter.ref() returned in the browser (send it up with your signup form) or an affiliate code.

curl -X POST https://referralmeter.com/api/v1/referrals \
  -H "Authorization: Bearer $REFERRALMETER_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"email":"new.user@example.com","external_id":"user_42","referral":"<referralmeter.ref()>","ip":"203.0.113.7"}'

Pass the visitor's ip so the self-referral check still works.

Record a sale

curl -X POST https://referralmeter.com/api/v1/track/sale \
  -H "Authorization: Bearer $REFERRALMETER_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"event_id":"pay_123","amount":4900,"currency":"usd","customer_external_id":"user_42","kind":"subscription"}'
  • amount is in cents. event_id is your idempotency key: sending it twice records it once.
  • Later sales for the same customer_external_id, customer_id or email attribute to the same affiliate without a referral.
  • kind: subscription, one_time, credits or usage. Your commission rules decide which kinds pay.
  • livemode: false records a test sale that is never paid out.

Record a refund

curl -X POST https://referralmeter.com/api/v1/track/refund \
  -H "Authorization: Bearer $REFERRALMETER_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"event_id":"ref_9","payment_id":"pay_123","amount":4900}'

Partial refunds claw back the same share of the commission. A commission that was already paid is deducted from the affiliate's next payout.