Gift inventory¶
The gift inventory lists the premium gift codes that the current account bought, along with whether each code has been redeemed. Public gift lookup and redemption are in the Gifts resource. Purchases go through the Billing resource, and TEBHOS processes payments with Polar.
A code is added to this inventory only when a gift checkout is paid without a recipient. When the buyer picks a friend at checkout, TEBHOS gives premium straight to that friend and does not create a code, so nothing appears here.
A gift you received never appears in the inventory
Only the account that bought a code sees it here.
Unread marker not raised on TEBHOS
The user object has has_unread_gift_inventory and unread_gift_inventory_count, and Modify current user accepts has_unread_gift_inventory: false. TEBHOS does not currently raise this marker when a new code is issued, so it stays false / 0. Call List current user gifts instead of waiting for the marker.
Gift inventory object¶
One gift code bought by the current account, with its redemption state. A paid order produces at most one code, even if the payment provider sends its notification more than once.
Structure¶
| Field | Type | Description |
|---|---|---|
| code | string | The code a recipient enters in Redeem gift. Purchased codes are 32 lowercase hexadecimal characters |
| duration_type | string | The unit of duration_quantity: days, weeks, months or years. Purchased codes always use months |
| duration_quantity | integer | How many duration_type units the code grants. For a purchased code, this is the number of months bought (at least 1) |
| created_at | ISO8601 timestamp | When the code was created |
| created_by | ?object | The buyer, which is always the current account, as {"username", "name"}. Null if the account record cannot be read |
| redeemed_at | ?ISO8601 timestamp | When the code was redeemed, or null if it has not been redeemed |
| redeemed_by | ?object | The account that redeemed the code, as {"username", "name"}, or null |
created_by and redeemed_by contain only username and name (the display name). They do not include a user ID. redeemed_by can be null for a redeemed code whose redeemer account no longer exists, so use redeemed_at to tell whether a code has been redeemed.
When a code is redeemed, the redeemer's premium is extended by the code's duration. TEBHOS counts a month as 30 days and a year as 365 days.
A code works like a password
TEBHOS does not record a recipient when a code is issued. Redemption gives the code to the first eligible account that presents it. The inventory returns the full code, and a redeemed code cannot be reset. Keep every unredeemed code secret.
Example¶
{
"code": "3f9c2a7e5b1d4c8e9a0b6d2f7c4e1a85",
"duration_type": "months",
"duration_quantity": 1,
"created_at": "2026-09-11T12:04:33.000+00:00",
"created_by": {"username": "aria", "name": "Aria"},
"redeemed_at": null,
"redeemed_by": null
}
List current user gifts¶
GET /users/@me/gifts
Lists the gift codes the current account bought, newest first. Returns an array of gift inventory objects.
The list is not paginated. It accepts no query parameters and returns no cursor.
An unredeemed code stays in the list for as long as it exists. A redeemed code is listed only for 7 days after it was redeemed, so an account whose codes were all redeemed earlier than that gets an empty array. A redeemed code that is no longer listed still exists, can still be looked up through the Gifts resource, and cannot be used again.
Response¶
| Status | Body | Condition |
|---|---|---|
| 200 | array of gift inventory objects | The inventory was returned |
| 403 | error response | A bot token was used (ACCESS_DENIED) |
Rate limit¶
40 requests per 10 seconds per user, on the gifts:list bucket. See Rate limits.
Get gift inventory (settings view)¶
GET /auth/me/gifts
Returns the same codes with the same rules (bought by the caller, redeemed codes hidden after 7 days, newest first), in the shape used by the gifts tab in TEBHOS settings. The array is wrapped in a gifts object.
| Field | Type | Description |
|---|---|---|
| code | string | The gift code |
| duration_type | string | As in the gift inventory object. Defaults to months if not stored |
| duration_quantity | integer | As in the gift inventory object. Defaults to 1 if not stored |
| duration_months | integer | The duration in months: duration_quantity for months, duration_quantity × 12 for years, and 1 for days or weeks |
| created_at | ISO8601 timestamp | When the code was created |
| redeemed_at | ?ISO8601 timestamp | When the code was redeemed, or null |
| redeemed_by_username | ?string | The username of the redeemer, or null |
{
"gifts": [
{
"code": "3f9c2a7e5b1d4c8e9a0b6d2f7c4e1a85",
"duration_months": 12,
"duration_type": "months",
"duration_quantity": 12,
"created_at": "2026-09-11T12:04:33.000+00:00",
"redeemed_at": "2026-09-12T08:00:10.000+00:00",
"redeemed_by_username": "deniz"
}
]
}
This route has no route-level rate limit. New integrations should use List current user gifts.