POST /v1/admin/referrals/users/{user_id}/tier — Override user referral tier

The referral program assigns each user a tier that determines their reward rate. Tiers are operator-set only — there is no automatic promotion based on activity, invitee count, or volume. This endpoint lets an operator move a user to a specific tier explicitly.

The request body carries the target tier (an integer that must match a tier defined in the platform's referral configuration) and an optional free-text note. The change is recorded to the referral audit trail along with the old→new transition and the note, so tier overrides are traceable.

On success the endpoint returns the previous tier and the newly applied tier. Changing a tier affects only future reward emissions — rewards that were already created keep the rate they were issued at; they are not recalculated.

Tier values come from the platform's referral config. The default table is:

Passing any tier value that is not present in that table returns invalid_tier.

Path parameters

Response fields

All errors use the shared envelope {"error": "<tag>"}. See errors.md for the full envelope.

JavaScript (fetch)

const userId = "3f9b2c10-7d4e-4a1b-9c2a-1e5f8b6d0a44";


const res = await fetch(
  `https://api.triport.io/v1/admin/referrals/users/${userId}/tier`,
  {
    method: "POST",
    headers: {
      "X-Admin-Token": process.env.TRIPORT_ADMIN_TOKEN,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ tier: 2, note: "Promoted: verified creator partner" }),
  }
);


if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`set tier failed: ${error}`);
}


const { old_tier, new_tier } = await res.json();
console.log(`tier ${old_tier} -> ${new_tier}`);

TypeScript SDK (@triport/sdk)

import { TriportAdmin } from "@triport/sdk";


const admin = new TriportAdmin({ adminToken: process.env.TRIPORT_ADMIN_TOKEN! });


const { oldTier, newTier } = await admin.referrals.setUserTier(
  "3f9b2c10-7d4e-4a1b-9c2a-1e5f8b6d0a44",
  { tier: 2, note: "Promoted: verified creator partner" }
);


console.log(`tier ${oldTier} -> ${newTier}`);

Python (triport-sdk)

import os
from triport import TriportAdmin


admin = TriportAdmin(admin_token=os.environ["TRIPORT_ADMIN_TOKEN"])


result = admin.referrals.set_user_tier(
    "3f9b2c10-7d4e-4a1b-9c2a-1e5f8b6d0a44",
    tier=2,
    note="Promoted: verified creator partner",
)


print(f"tier {result.old_tier} -> {result.new_tier}")

• Operator-only, no auto-promotion. A user's tier only ever changes through this endpoint. Nothing in the reward or invitee flow promotes a user automatically.
• Not retroactive. Setting a new tier changes only the rate applied to rewards emitted after the change. Existing rewards keep their original rate.
• Audit trail. Each call records a tier_changed attribution event with the old->new transition and the optional note.
• Request size limit. The JSON body is capped at 4 KiB; larger bodies fail with invalid_json.
• Related endpoints. Use GET /v1/admin/referrals/users/{user_id} to inspect a user's current tier, rate, balance, and recent attributions before overriding. Both routes require the X-Admin-Token header.