Gift codes
Each gift code gives premium to the first account that redeems it. People redeem them through Gifts.
Gift duration units
Section titled “Gift duration units”Gifts explains how a redeemed code extends premium.
| Value | Description |
|---|---|
| days | Days |
| weeks | Weeks |
| months | Calendar months |
| years | Calendar years |
| lifetime | Premium that never ends, and duration_quantity is ignored |
Create gift codes
Section titled “Create gift codes”POST/v1/admin/gift-codesGenerates gift codes and returns their redemption links. You need gift_codes:generate, and the instance's premium mode must be mirror.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| count | integer | The number of codes to generate (1-100) |
| duration_type | string | The gift duration unit |
| duration_quantity | integer | The number of units (1-3650), still required but ignored for lifetime |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| codes | array[string] | The redemption links, each in the form {gift URL}/{code} |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The codes were generated |
| 403 | error response | FEATURE_NOT_AVAILABLE_SELF_HOSTED when the premium mode is everyone |
The request records a generate_gift_codes audit entry without the codes.
The rate limit is 30 requests per minute, on the admin:code:generation bucket.
Revoke a gift code
Section titled “Revoke a gift code”DELETE/v1/admin/gift-codes/{code}Revokes a gift code that nobody has redeemed, so it can't be redeemed anymore. You need gift_codes:generate. Pass the code itself, which is the last part of the redemption link.
A redeemed code can't be revoked, because the premium it gave already belongs to the account that redeemed it. To take that premium back, use Remove user premium on that account. The error message names the account.
A code a customer bought can't be revoked here either. Refund the purchase instead, which revokes the code.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | none | The code was revoked |
| 400 | error response | INVALID_FORM_BODY when the code was redeemed or a customer bought it |
| 400 | error response | STRIPE_GIFT_REDEMPTION_IN_PROGRESS when someone is redeeming the code right now |
| 404 | error response | UNKNOWN_GIFT_CODE when the code doesn't exist or was already revoked |
The request records a revoke_gift_code audit entry with the code and its duration. A revoked code can't be redeemed, so the entry doesn't give premium to anyone who reads it.
The rate limit is 30 requests per minute, on the admin:code:generation bucket.