Gifts

A gift is a code that grants premium to the account that redeems it. Until then it belongs to no account. Create gift checkout defines how one is bought.

Both routes are hosted-only, as deployment availability describes. Redeem gift is user-only.

A code is a bearer credential

A gift records no recipient, so FiveCord binds the code to whichever eligible account presents it first. Get gift takes no credential and returns the full public record for any code. Treat an unredeemed code as a secret.

Gift object

A gift records a duration. FiveCord computes the entitlement window at redemption time. For a positive quantity, the entitlement anchor is the latest of the current time, the redeemer’s current premium end and their existing gift extension end.

Both creation paths record a creator. A completed gift checkout records the purchaser. An Admin API gift records the system account with ID 0, and no field names the administrator that requested it. No operation unredeems a code.

Structure

Field	Type	Description
code1	string	The code presented to Redeem gift
duration_type	string	The gift duration unit that duration_quantity is measured in
duration_quantity2	integer	The number of duration_type units the gift grants
redeemed3	boolean	Whether the code has already been redeemed
created_by?4	?partial user object	The account that created the gift

¹ Exactly 32 case-sensitive letters and digits

² Non-negative, and positive on every gift the current code paths create. The exact value 0 means lifetime Visionary entitlement and appears only on a record that predates that constraint

³ Neither the redemption time nor the redeeming account appears in this object

⁴ Always present and non-null on this route. A creator ID that resolves to no account becomes a placeholder partial with the unresolved ID, DeletedUser, 0000 and Deleted User

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

A purchased gift is always whole months or whole years, because a purchase of twelve months is normalised to one year. The day and week units exist for codes created through the Admin API.

Value	Description
days	The quantity counts days added to the entitlement anchor
weeks	The quantity counts weeks added to the entitlement anchor
months1	The quantity counts calendar months added to the entitlement anchor
years1	The quantity counts calendar years, applied as twelve calendar months each

¹ A calendar month is added in UTC and clamped to the last day of the target month, so 31 January extended by one month lands on 28 or 29 February

Get gift

GET/v1/gifts/{code}Unauthenticated

Reads a gift by its code. Returns the gift object on success.

A code that does not exist and one that has been revoked both return 404 UNKNOWN_GIFT_CODE, so a revoked code is never distinguishable from one that was never issued.

A chargeback or a refund for the purchase revokes the gift when Receive Stripe webhook processes it and the gift is still unredeemed. The gift also leaves List current user gifts, so the buyer has no route that reports the reversal. A gift that was already redeemed when the same event arrives stays readable, and FiveCord recomputes the redeemer’s entitlement from their remaining redeemed gifts.

Path parameters

Field	Type	Description
code	string	The code to look up (1-32 characters)

Response

Status	Body	Condition
200	gift object	The gift was returned
404	error response	No gift exists for the code, or the gift was revoked, and the request returns UNKNOWN_GIFT_CODE

Rate limit

60 requests per 10 seconds for each authenticated user or client IP address, on the gift:get bucket. A supplied credential only keys the bucket. A credential that does not resolve leaves the bucket keyed by the client IP address, and the request still succeeds.

Redeem gift

POST/v1/gifts/{code}/redeem

Redeems a gift for the authenticated account and returns 204 with an empty body. User-only. Emits a User Update Gateway event.

Limitations

• The redeeming account must be claimed, and an unclaimed account returns 400 UNCLAIMED_ACCOUNT_CANNOT_MAKE_PURCHASES.
• The account must have a verified email address, and an unverified address returns 403 PURCHASE_EMAIL_VERIFICATION_REQUIRED.
• The account must not have the purchase-disabled premium flag, and the flag returns 403 PREMIUM_PURCHASE_BLOCKED with a top-level reason member set to purchase_disabled.
• An account already holding lifetime Visionary entitlement receives 400 CANNOT_REDEEM_PLUTONIUM_WITH_VISIONARY.

A consumed code receives 400 GIFT_CODE_ALREADY_REDEEMED. A code another request is redeeming receives 400 STRIPE_GIFT_REDEMPTION_IN_PROGRESS. A code that does not exist or has been revoked receives 404 UNKNOWN_GIFT_CODE.

The refusal order differs from checkout

The claimed account, verified email and purchase flag refusals are evaluated before the lifetime refusal here. Create subscription checkout evaluates the same groups in the opposite order.

Redemption is single-use per code

One redemption can be in flight for a code across the whole deployment, and a second concurrent request is refused at once.

Path parameters

Field	Type	Description
code	string	The code to redeem (1-32 characters)

Request headers

Field	Type	Description
X-Captcha-Token?1	string	The proof issued by the CAPTCHA provider
X-Captcha-Type?2	string	The CAPTCHA provider, either hcaptcha or turnstile

¹ A missing proof returns 400 CAPTCHA_REQUIRED and a rejected proof returns 400 INVALID_CAPTCHA. Verification is skipped when CAPTCHA is disabled, when the account has the exemption flag, or when the account’s email address has the captcha_exempt account policy capability, as described by CAPTCHA handling

² Any other value, including an omitted header, falls back to the instance’s configured provider

Response

Status	Body	Condition
204	empty	The gift was redeemed and the entitlement was applied
400	error response	CAPTCHA failed, the code is redeemed or a redemption is in flight, the account is unclaimed or holds lifetime entitlement, the payment provider rejected the change to the active subscription, or the Visionary guild join for a lifetime gift failed
403	error response	The email address is unverified, or purchases are disabled for the account
404	error response	No gift exists for the code, the gift was revoked, the authenticated account record no longer exists, or the configured Visionary guild does not exist

Side effects

The gift becomes redeemed, so Get gift reports redeemed as true and List current user gifts shows the redemption time and the redeemer to the buyer.

A positive quantity extends premium from the latest of the current time, the current premium end and the existing gift extension end. When the account has a subscription with the payment provider and its subscription premium has not ended, FiveCord also extends that subscription’s trial or billing period without proration. A provider failure can return 400 STRIPE_ERROR and leave the code unredeemed.

A quantity of 0 grants lifetime Visionary premium and immediately cancels an active subscription without proration or a final invoice. When the gift record has a Visionary sequence number, the redeemer receives that number as their lifetime Visionary sequence and joins the Visionary guild.

A failed Visionary guild join leaves the gift unredeemed. Guild limits return 400 MAX_GUILDS or MAX_GUILD_MEMBERS. Any subscription cancellation already completed is not reversed.

Entitlement changes send User Update to the redeemer’s sessions.

Rate limit

10 requests per minute for each authenticated user, on the gift:redeem bucket.