Gifts

A gift is a code that grants premium to the account that redeems it. Create gift checkout buys one. The routes on this page work only while the instance premium mode is mirror.

Anyone who has an unredeemed code can look it up and redeem it. Keep the code secret until you give it away.

Gift object

A gift grants premium for a set duration.

Structure

Field	Type	Description
code¹	string	The code to pass to Redeem gift
duration_type	string	The duration unit of `duration_quantity`
duration_quantity²	integer	The number of units the gift grants
redeemed	boolean	Whether the code has been redeemed
created_by?³	?partial user object	The account that created the gift

¹ 32 case-sensitive letters and digits

² A value of 0 grants lifetime premium

³ For a gift created through the Admin API, created_by is the administrator who created it

Example

{
  "code": "aZ3kQ9mR2tX7bN4vC8wL5yH1sD6gF0pJ",
  "duration_type": "months",
  "duration_quantity": 1,
  "redeemed": false,
  "created_by": {
    "id": "1501314428688998182",
    "username": "quill",
    "discriminator": "0001",
    "global_name": "Quill",
    "avatar": null,
    "avatar_color": null,
    "flags": 0
  }
}

Gift duration units

Bought gifts use months or years, and only gifts created through the Admin API use days or weeks.

Value	Description
days	Periods of 24 hours
weeks	Periods of seven 24-hour days
months	Calendar months, clamped to the last day of the target month
years	12 calendar months

Get gift

GET/v1/gifts/{code}

Unauthenticated

Returns a gift.

Response

Status	Body	Condition
200	gift object	The gift was returned
404	error response	`UNKNOWN_GIFT_CODE` when the code does not exist or was revoked after a refund

The rate limit is 60 requests per 10 seconds, on the gift:get bucket.

Redeem gift

POST/v1/gifts/{code}/redeem

Redeems a gift for the current user and sends a User Update Gateway event. You need a claimed account.

A gift adds its duration after any premium the account already has and pushes back the next charge of an active subscription. A lifetime gift (duration_quantity of 0) cancels an active subscription.

Request headers

Field	Type	Description
X-Captcha-Token?	string	The solved ALTCHA challenge, see CAPTCHA handling

Response

Status	Body	Condition
204	empty	The gift was redeemed
400	error response	`GIFT_CODE_ALREADY_REDEEMED` when the code was already redeemed
400	error response	`STRIPE_GIFT_REDEMPTION_IN_PROGRESS` when the same code is being redeemed at the same time
400	error response	`STRIPE_ERROR` when the payment provider rejects the change to an active subscription. The code stays unredeemed
400	error response	`CANNOT_REDEEM_PLUTONIUM_WITH_VISIONARY` when the account has lifetime premium
403	error response	`ACCOUNT_VERIFICATION_REQUIRED` for an unclaimed account
404	error response	`UNKNOWN_GIFT_CODE` when the code does not exist or was revoked

The rate limit is 10 requests per minute, on the gift:redeem bucket.