--- # SPDX-License-Identifier: AGPL-3.0-or-later title: Gifts description: Gift code objects, duration units, public lookup, and one-time redemption. --- import RouteHeader from '@/components/RouteHeader.astro'; A gift is a code that grants premium to the account that redeems it. Until then it belongs to no account. [Create gift checkout](/http-api/billing/#create-gift-checkout) defines how one is bought. A self-hosted deployment serves both routes only while its [premium mode](/admin-api/instance/#premium-modes) is `mirror`, as [deployment availability](/http-api/deployment-availability/) describes. [Redeem gift](#redeem-gift) is user-only. :::caution[A code is a bearer credential] A gift records no recipient, so Fluxer binds the code to whichever eligible account presents it first. [Get gift](#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. Fluxer 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](#redeem-gift) | | duration_type | string | The [gift duration unit](#gift-duration-units) 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](/http-api/users/#partial-user-object) object | The account that created the gift | 1 Exactly 32 case-sensitive letters and digits 2 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 3 Neither the redemption time nor the redeeming account appears in this object 4 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 ```json { "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 | 1 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 Reads a gift by its code. Returns the [gift](#gift-object) 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](/http-api/billing/#receive-stripe-webhook) processes it and the gift is still unredeemed. The gift also leaves [List current user gifts](/http-api/users/gifts/#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 Fluxer 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](#gift-object) object | The gift was returned | | 404 | [error response](/http-api/#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 Redeems a gift for the authenticated account and returns 204 with an empty body. User-only. Emits a [User Update](/gateway/events/#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`. :::note[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](/http-api/billing/#create-subscription-checkout) evaluates the same groups in the opposite order. ::: :::caution[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 solved ALTCHA challenge, see [CAPTCHA handling](/topics/captcha/) | 1 A missing token returns 400 `CAPTCHA_REQUIRED` and a rejected token returns 400 `INVALID_CAPTCHA`, each with a new challenge. Verification is skipped when the check is off for the instance, when the account has the exemption flag, or when the account's email address is on an exempt domain ### Response | Status | Body | Condition | | --- | --- | --- | | 204 | empty | The gift was redeemed and the entitlement was applied | | 400 | [error response](/http-api/#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](/http-api/#error-response) | The email address is unverified, or purchases are disabled for the account | | 404 | [error response](/http-api/#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](#get-gift) reports `redeemed` as true and [List current user gifts](/http-api/users/gifts/#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, Fluxer 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](/http-api/premium/#rejoin-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](/gateway/events/#user-update) to the redeemer's sessions. ### Rate limit 10 requests per minute for each authenticated user, on the `gift:redeem` bucket.