Referrals

Create referral and promo codes that reward both the referrer and the referee with virtual currency.

How it works

1. Admin creates a referral code with rewards for both parties
2. User shares their referral code
3. When the code is redeemed, both users receive their rewards
4. Usage is tracked with claim counts and optional limits

MCP tools

Example

Agent: "Create a referral program that gives 100 gold to both users"

amba_referrals_create({
  project_id: "proj_xxx",
  code: "FRIEND100",
  reward_referrer: { "gold": 100 },
  reward_referee: { "gold": 100 },
  max_uses: 1000
})

Client API reference

Amba.referrals.getReferralCode() and Amba.referrals.claimReferral(code) call these routes. getReferralCode() returns { id, code, owner_id, uses_count, max_uses, created_at }. claimReferral(code) returns { id, code_id, referrer_id, referee_id, reward, claimed_at }; referrer_id is null for a code no user owns (one you created for a team or a campaign), and reward is what the code grants the user who claimed it.

Claim a referral code

POST /v1/client/referrals/claim
{
  "code": "FRIEND100"
}

A user can be referred by one other user: after claiming one user's code, a claim of another user's code answers 400 ALREADY_REFERRED. A code your team creates (no owning user) can be claimed once by each user, up to its max_uses. Other refusals are 404 INVALID_CODE, 400 SELF_REFERRAL, 400 ALREADY_CLAIMED and 400 MAX_USES_REACHED.