Premium Referral Resource

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 trial ID associated with the referral
subscription_trial	subscription trial object (todo)	The subscription trial associated with the referral
expires_at	ISO8601 timestamp	The expiry date of the referral link
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

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

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
  }
}

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 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

Preview Premium Referral

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

Checks whether you can send a referral to the user specified.

Response Body

Field	Type	Description
is_eligible	boolean	Whether you can send a referral to the user specified

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.