Premium Referrals

Premium referrals, or Nitro trials, allow Nitro subscribers to share up to three 2-week Nitro subscriptions with friends who haven't had an active Nitro subscription in the past 12 months.

Premium Referral Object

Premium Referral Structure

Field	Type	Description
id	snowflake	The ID of the referral
user_id	snowflake	The user who the referral was sent to
trial_id	snowflake	The ID of the subscription trial associated with the referral
subscription_trial	subscription trial object	The subscription trial associated with the referral
expires_at	ISO8601 timestamp	When the referral link expires
referrer_id	snowflake	The ID of the user who created the referral
referrer	partial user object	The user who created the referral
redeemed_at?	ISO8601 timestamp	When the referral was redeemed

Example Premium Referral

{
  "id": "1107800271637200936",
  "user_id": "563434444321587202",
  "trial_id": "1073698058383917056",
  "subscription_trial": {
    "id": "1073698058383917056",
    "interval": 3,
    "interval_count": 14,
    "sku_id": "521847234246082599"
  },
  "expires_at": "2023-05-17T22:42:46.690847+00:00",
  "referrer_id": "1044657759066525777",
  "referer": {
    "id": "1044657759066525777",
    "username": "hackermon",
    "global_name": "daniel",
    "avatar": null,
    "avatar_decoration_data": null,
    "discriminator": "0",
    "public_flags": 16384,
    "primary_guild": null
  },
  "redeemed_at": "2023-05-16T18:22:21.777456+00:00"
}

Premium Referral Eligibility Object

Premium Referral Eligibility Structure

Field	Type	Description
referrals_remaining	integer	The amount of referrals remaining
sent_user_ids	array[snowflake]	The IDs of users that have been referred
refresh_at	?ISO8601 timestamp	When the referral count will refresh
has_eligible_friends	boolean	Whether the user has friends that are eligible for a referral
recipient_status	map[snowflake, integer]	The redemption status of each referred user ID
is_eligible_for_incentive	boolean	Whether the user is eligible for a personal discount upon referral redemption
is_qualified_for_incentive	boolean	Whether the user will receive an incentivized discount on their next Nitro purchase
referral_incentive_status	integer	The incentive status of the user

Premium Referral Recipient Status

Value	Name	Description
1	REDEEMED	The recipient has redeemed the referral
2	PENDING	The recipient has yet to redeem the referral

Premium Referral Incentive Status

Value	Name	Description
0	NOT_ELIGIBLE	The user is not eligible for an incentive
1	ELIGIBLE	The user is eligible for an incentive
2	QUALIFIED	The user will receive an incentivized discount on their next Nitro purchase
3	COOLDOWN	The user is on cooldown and cannot receive an incentive
4	UNAPPLIED	The user has not applied their incentive yet

Example Premium Referral Eligibility

{
  "referrals_remaining": 0,
  "sent_user_ids": ["159985870458322944", "563434444321587202", "296776625432035328"],
  "refresh_at": null,
  "has_eligible_friends": true,
  "recipient_status": {
    "159985870458322944": 2,
    "563434444321587202": 2,
    "296776625432035328": 2
  },
  "is_eligible_for_incentive": false,
  "is_qualified_for_incentive": false,
  "referral_incentive_status": 0
}

Endpoints

Get Premium Referral

GET/referrals/{referral.id}

Returns a premium referral object for the given referral ID.

Get Premium Referral Eligibility

GET/users/@me/referrals/eligibility

Returns a premium referral eligibility object for the user.

Get Premium Referral Incentive Eligibility

GET/users/@me/referrals/incentive-eligibility

Returns a subset of the premium referral eligibility object for the user with their eligibility for a personal discount upon referral redemption.

Response Body

Field	Type	Description
is_eligible_for_incentive	boolean	Whether the user is eligible for a personal discount upon referral redemption

Get Premium Referral Eligible Users

POST/users/@me/referrals/eligible-users

Returns an object containing a list of users who are eligible to receive a referral from the user.

JSON Params

Field	Type	Description
index	integer	The current search index (0-1000)
limit?	integer	Max number of users to return (max 50, default 30)
search_query?	string	Query to match usernames against (max 1024 characters)

Response Body

Field	Type	Description
users	array[partial user object]	The eligible users
next_index?	integer	The next index to paginate from

Create Premium Referral

POST/users/@me/referrals/{user.id}

Creates a new premium referral. Returns a premium referral object. Fires a Message Create Gateway event. The referral is sent to the user specified. Referrals expire after 48 hours.