Gifts¶
A gift code grants TEBHOS Pro time to the account that redeems it. Until then it belongs to no account.
Buying a gift
TEBHOS Pro bought as a gift through Create gift checkout is applied directly to the chosen friend. The purchase is still recorded as a gift code, already marked as redeemed by the recipient. If the recipient has lifetime premium, the code is left unredeemed so the buyer can pass it on. The codes a user has bought are listed by List my gifts.
A code is a bearer credential
A gift code names no recipient; whoever redeems it first receives the time. Get gift needs no credential. Treat an unredeemed code as a secret.
Gift object¶
Structure¶
| Field | Type | Description |
|---|---|---|
| code | string | The code, 32 lowercase hexadecimal characters |
| duration_type | ?string | The gift duration unit |
| duration_quantity | ?integer | The number of duration_type units the gift grants |
| redeemed | boolean | Whether the code has already been redeemed |
| created_by | ?object | {username, name} of the account that bought or created the gift, or null when it cannot be resolved |
Example¶
{
"code": "3f9c1e2d4b5a60718293a4b5c6d7e8f9",
"duration_type": "months",
"duration_quantity": 1,
"redeemed": false,
"created_by": { "username": "example", "name": "Example" }
}
Gift duration units¶
| Value | Days added per unit |
|---|---|
| days | 1 |
| weeks | 7 |
| months | 30 |
| years | 365 |
Codes created from purchases always use months. An unrecognised unit is treated as months.
Get gift¶
GET /gifts/{code}
Returns the gift object for a code. No authentication is required.
Response¶
| Status | Body | Condition |
|---|---|---|
| 200 | gift object | The code exists |
| 404 | error response | No gift has this code (NOT_FOUND, message UNKNOWN_GIFT_CODE) |
Rate limit¶
60 requests per 10 seconds per client, on the gift:get bucket.
Example¶
Redeem gift¶
POST /gifts/{code}/redeem
Redeems a gift code for the authenticated account and returns 204 with an empty body. User-only: a bot token is rejected with 403 ACCESS_DENIED.
The gift's duration is added on top of the account's current premium end date, so an active subscription is extended rather than replaced.
Response¶
The error code is the generic HTTP code; the specific reason is in message.
| Status | Body | Condition |
|---|---|---|
| 204 | empty | The code was redeemed and premium was extended |
| 400 | error response | message GIFT_CODE_ALREADY_REDEEMED: the code was already used |
| 400 | error response | message GIFT_CODE_REDEMPTION_IN_PROGRESS: another redemption of the same code is running |
| 400 | error response | message CANNOT_REDEEM_WITH_LIFETIME: the account already has lifetime premium; the code can be passed to a friend instead |
| 404 | error response | message UNKNOWN_GIFT_CODE: no gift has this code |
Side effects¶
Redemption is protected by a per-code lock, so two simultaneous requests cannot both succeed. If extending premium fails, the code is released again and can be retried.
Rate limit¶
10 requests per minute per user, on the gift:redeem bucket.