Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
4.0 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Gifts
description: Gift code objects, duration units, public lookup and redemption.
---

import RouteHeader from '@/components/RouteHeader.astro';

A gift is a code that grants premium to the account that redeems it. [Create gift checkout](/http-api/billing/#create-gift-checkout) buys one. The routes on this page work only while the instance [premium mode](/admin-api/instance/#premium-modes) 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<sup>1</sup> | string | The code to pass to [Redeem gift](#redeem-gift) |
| duration_type | string | The [duration unit](#gift-duration-units) of `duration_quantity` |
| duration_quantity<sup>2</sup> | integer | The number of units the gift grants |
| redeemed | boolean | Whether the code has been redeemed |
| created_by?<sup>3</sup> | ?[partial user](/http-api/users/#partial-user-object) object | The account that created the gift |

<sup>1</sup> 32 case-sensitive letters and digits

<sup>2</sup> A value of `0` grants lifetime premium

<sup>3</sup> For a gift created through the Admin API, `created_by` is the administrator who created it

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

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

<RouteHeader method="GET" path="/v1/gifts/{code}" unauthenticated />

Returns a [gift](#gift-object).

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [gift](#gift-object) object | The gift was returned |
| 404 | [error response](/http-api/#error-response) | `UNKNOWN_GIFT_CODE` when the code does not exist or was revoked, after a refund or by an instance admin |

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

## Redeem gift

<RouteHeader method="POST" path="/v1/gifts/{code}/redeem" />

Redeems a gift for the current user and sends a [User Update](/gateway/events/#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](/topics/captcha/) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The gift was redeemed |
| 400 | [error response](/http-api/#error-response) | `GIFT_CODE_ALREADY_REDEEMED` when the code was already redeemed |
| 400 | [error response](/http-api/#error-response) | `STRIPE_GIFT_REDEMPTION_IN_PROGRESS` when the same code is being redeemed at the same time |
| 400 | [error response](/http-api/#error-response) | `STRIPE_ERROR` when the payment provider rejects the change to an active subscription. The code stays unredeemed |
| 400 | [error response](/http-api/#error-response) | `CANNOT_REDEEM_PLUTONIUM_WITH_VISIONARY` when the account has lifetime premium |
| 403 | [error response](/http-api/#error-response) | `ACCOUNT_VERIFICATION_REQUIRED` for an unclaimed account |
| 404 | [error response](/http-api/#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.