Question 1

Why did my referral attribution not fire?

Accepted Answer

The most common cause is the referral code never reaching the capture call. The public link GET /r/{slug}/{code} 302-redirects to your app with ?ref=<code> appended; your signup page has to read that ref and send it as code to POST /v1/signups. If the code is absent, attribution has nothing to bind.

Question 2

The ?ref parameter is on my landing page but attribution is unreliable. Why?

Accepted Answer

The code is dropping during the auth round-trip. OAuth redirects and email confirmation links lose the query string. Persist ref on first hit in a cookie or localStorage, then read it back at account creation and send it as code to POST /v1/signups.

Question 3

Is it safe if my signup handler double-fires with a random idempotency key?

Accepted Answer

Yes. The same key replays the cached response, and a fresh key still returns the existing attribution with 200 because the server allows one attribution per account and replays the existing one for the same code. The tidier pattern is a derived key, signup-${externalUserId}, so each account has one deterministic key.

Question 4

When does simplereferral return 422 idempotency_key_reused?

Accepted Answer

When the same Idempotency-Key value is sent with a different body. A key caches only its first 2xx response, so reusing one key across different requests, for example the mint call and the capture call, is rejected. Derive a stable per-account key instead.

Question 5

Does simplereferral block fraudulent referral signups?

Accepted Answer

At capture time the API blocks only the trivial case, 422 self_referral, when the code owner signs up under their own code. Everything else attributes first-wins. Deeper fraud detection is on the roadmap, so screen referred signups and gate rewards inside your own app today.

Question 6

Do I need to sync users to simplereferral before capturing a referral?

Accepted Answer

No. There is no user sync. Everything is keyed by your own externalUserId, and POST /v1/signups creates the binding on the spot.

Would your referral attribution actually fire?

Or never debug attribution again.