Skip to content
Resenha API

Gift codes

Each gift code gives premium to the first account that redeems it. People redeem them through Gifts.

Gifts explains how a redeemed code extends premium.

ValueDescription
daysDays
weeksWeeks
monthsCalendar months
yearsCalendar years
lifetimePremium that never ends, and duration_quantity is ignored
POST/v1/admin/gift-codesAudit reason

Generates gift codes and returns their redemption links. You need gift_codes:generate, and the instance's premium mode must be mirror.

FieldTypeDescription
countintegerThe number of codes to generate (1-100)
duration_typestringThe gift duration unit
duration_quantityintegerThe number of units (1-3650), still required but ignored for lifetime
FieldTypeDescription
codesarray[string]The redemption links, each in the form {gift URL}/{code}
StatusBodyCondition
200response bodyThe codes were generated
403error responseFEATURE_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.

DELETE/v1/admin/gift-codes/{code}Audit reason

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.

StatusBodyCondition
204noneThe code was revoked
400error responseINVALID_FORM_BODY when the code was redeemed or a customer bought it
400error responseSTRIPE_GIFT_REDEMPTION_IN_PROGRESS when someone is redeeming the code right now
404error responseUNKNOWN_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.