Creating Referral Programs

Base URL: use the Admin Gateway for everything in this file (POST / PUT / DELETE below), e.g. https://admin-gateway.<env>/v1/....
Do not call these paths on the Query Gateway — they will return 404 (Query Gateway only serves gamer-facing GETs under /v1/referral/* and /v1/affiliate/*).

Overview

Creating referral flows typically includes:

1. Creating referral campaigns (admin setup)
2. Creating affiliate tiers and commission rules (optional)
3. Creating or generating referral codes
4. Applying a referral code for a user
5. Configuring hierarchy settings (optional)

After data exists, use GET / PUT / DELETE on the same Admin Gateway resources to read, update, or remove records — see Querying Referrals for response shapes and the full route table.

Create Referral Campaigns

Campaigns control how referral rewards are configured.

Endpoint:

POST /v1/referral/campaigns?tenant_id={tenant_id}
Authorization: Bearer <ADMIN_JWT>

Example Request:

{
  "name": "Welcome Bonus Campaign",
  "qualifying_event": "deposit.completed",
  "qualifying_filter": null,
  "referrer_rewards": {
    "wallet": [{ "currency_id": "points", "amount": 100 }]
  },
  "referee_rewards": {
    "wallet": [{ "currency_id": "points", "amount": 50 }]
  },
  "active": true,
  "starts_at": null,
  "ends_at": null
}

Typical success response: 200 with a full campaign object (same JSON shape as GET by id).

Create Referral Codes

Users can create their own codes.

Endpoint:

POST /v1/referral/codes
Authorization: Bearer <JWT>

Example Request:

{
  "code": "ALICE2026",
  "usage_limit": 100
}

If code is omitted, a generated code can be returned depending on your product behavior.

Apply a Referral Code

Attach an inviter code to the current authenticated user.

Endpoint:

POST /v1/referral/apply-code
Authorization: Bearer <JWT>

Example Request:

{
  "code": "ALICE2026"
}

Create Affiliates (Optional)

Approve or create an affiliate account.

Endpoint:

POST /v1/affiliates?tenant_id={tenant_id}
Authorization: Bearer <ADMIN_JWT>

Example Request:

{
  "user_id": "partner_001",
  "affiliate_code": "PARTNER001",
  "status": "active"
}

Create Affiliate Tiers (Optional)

Define commission tiers.

Endpoint:

POST /v1/affiliate/tiers?tenant_id={tenant_id}
Authorization: Bearer <ADMIN_JWT>

Example Request:

{
  "name": "Gold",
  "commission_rate": 0.05,
  "min_referrals": 10,
  "min_referee_revenue": 100000,
  "priority": 20
}

Create Commission Rules (Optional)

Define what events create commissions.

Endpoint:

POST /v1/affiliate/commission-rules?tenant_id={tenant_id}
Authorization: Bearer <ADMIN_JWT>

Example Request:

{
  "name": "Deposit Commission",
  "event_type": "deposit.completed",
  "event_filter": null,
  "commission_field": "amount",
  "use_tier_rate": true,
  "custom_rate": null,
  "currency_id": "points"
}

Affiliate hierarchy (REST)

Multi-level affiliate behavior uses two resource types:

tenant_id is resolved from the JWT for tenant admins, or supplied as ?tenant_id= for super/client admins.

1. Tenant hierarchy policy (singleton)

One configuration per tenant: max depth, level rates, active.

There is no POST on this singleton: creation is defined by the first successful PUT, which matches common REST usage for “put representation at this URL.”

Request body (PUT):

{
  "max_depth": 3,
  "level_rates": [0.05, 0.02, 0.01],
  "active": true
}

Compatibility: GET and PUT on /v1/affiliate/hierarchy-config?tenant_id= behave the same (deprecated alias; prefer /hierarchy).

2. Affiliate upline (sub-resource)

The hierarchy placement of a specific affiliate (who is the parent upline) is modeled as a sub-resource of that affiliate.

Request body (PUT):

{
  "parent_affiliate_id": "f8f0d620-6585-4d12-83d5-3077187b9f04"
}

To detach from an upline without DELETE, send:

{
  "parent_affiliate_id": null
}

Compatibility: PUT /v1/affiliates/{affiliate_id}/parent?tenant_id= with the same JSON body is supported (deprecated alias; prefer /hierarchy).

3. Downline (read-only collection)

End-users use the Query Gateway mirror: GET /v1/affiliate/downline (gamer JWT).

Update and delete (Admin Gateway)

Use these when building admin UIs (detail screens, edit forms, delete with confirmation).

• PUT bodies match the create payloads for that resource (see sections above); for campaigns, include the same fields as POST (including optional starts_at / ends_at).
• DELETE returns an empty body with status 204 No Content on success.

Full JSON examples for each entity are in Querying Referrals.

Best Practices

1. Keep referral codes easy to share and type
2. Use clear qualification rules users can understand
3. Keep affiliate approval and suspension flows explicit
4. Add idempotency and retries in client-side admin tools
5. Test campaign rules before wide rollout

Next Steps

• Querying Results - Learn how to retrieve referral data
• Referral Overview - Understand the referral system