Gift codes
Admin gift code generation issues premium codes in bulk, each one redeemable once and each granting a fixed span of entitlement. Gifts defines the public record of a code and its single redemption.
This resource has three operations: generating premium codes, generating item codes that each give one cosmetic item, and revoking unredeemed codes of either kind. No Admin operation lists or redeems a code, or reports who redeemed one.
Gift duration units
Section titled “Gift duration units”The unit and the quantity together define the span a redeemed code grants. At redemption, Micup adds the span to the entitlement anchor, which is the latest of the current time, the end of the redeemer’s premium, and the end of any earlier gift extension. Lifetime gifts are not supported.
| Value | Description |
|---|---|
| days | The quantity counts days added to the entitlement anchor |
| weeks | The quantity counts weeks added to the entitlement anchor |
| months1 | The quantity counts calendar months added to the entitlement anchor |
| years1 | The quantity counts calendar years, applied as twelve calendar months each |
1 A calendar month is added in UTC and clamped to the last day of the target month, so an anchor of 31 January extended by one month lands on 28 or 29 February
Create gift codes
Section titled “Create gift codes”POST/v1/admin/gift-codesGenerates the requested number of unredeemed gift codes. Requires gift_codes:generate. Returns the complete redemption links on success.
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 the quantity is counted in |
| duration_quantity | integer | The quantity of the selected unit (1-3650) |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| codes1 | array[string] | The complete redemption links, one for each generated code, in generation order |
1 Each link uses the instance’s configured gift endpoint followed by / and the code
{ "codes": [ "https://example.com/gift/aB3dEfGhIjKlMnOpQrStUvWxYz012345", "https://example.com/gift/Zy9XwVuTsRqPoNmLkJiHgFeDcBa543210" ]}Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The codes were generated |
| 4031 | error response | The account lacks admin:authenticate or gift_codes:generate, or the instance is self-hosted in the everyone premium mode |
1 Returned as MISSING_PERMISSIONS without admin:authenticate, as MISSING_ACL with that but without gift_codes:generate, and as FEATURE_NOT_AVAILABLE_SELF_HOSTED on a self-hosted instance in the everyone premium mode
Side effects
Section titled “Side effects”Each code is 32 characters drawn from the uppercase letters, the lowercase letters, and the digits. Micup creates it unredeemed and records the system account with ID 0 as its creator, which is the creator the gift object reports to the redeemer.
A failed request can leave some codes redeemable without returning them. Retrying can therefore create additional codes.
The operation records one Admin audit entry with action generate_gift_codes, target type gift_code, target ID 0, and metadata keys count, duration_type, and duration_quantity. The codes are not recorded. It emits no Gateway Dispatch.
Rate limit
Section titled “Rate limit”30 requests per minute for each authenticated user, on the admin:code:generation bucket.
Create item codes
Section titled “Create item codes”POST/v1/admin/gift-codes/cosmeticGenerates the requested number of unredeemed item codes, each giving one owned-availability cosmetic item instead of premium time. Requires both gift_codes:generate and cosmetics:manage. Returns the complete redemption links on success.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| count | integer | The number of codes to generate (1-100) |
| item_id | snowflake | The owned-availability cosmetic item each code gives |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The codes were generated, returned as in Create gift codes |
| 400 | error response | The body fails validation, or the item is unknown or not owned-availability, returned as INVALID_FORM_BODY |
| 4031 | error response | The account lacks an ACL, or the instance is self-hosted outside the mirror premium mode |
1 Returned as MISSING_PERMISSIONS without admin:authenticate, as MISSING_ACL without gift_codes:generate or cosmetics:manage, and as FEATURE_NOT_AVAILABLE_SELF_HOSTED on a self-hosted instance with the everyone premium mode
Side effects
Section titled “Side effects”The codes have the same shape and creator as premium codes, and carry the item in place of a duration. Get gift answers them with 404, Get code preview shows the item, and Revoke gift codes revokes them like premium codes.
The operation records one Admin audit entry with action generate_cosmetic_gift_codes, target type gift_code, target ID 0, and metadata keys count and item_id. The codes are not recorded. It emits no Gateway Dispatch.
Rate limit
Section titled “Rate limit”30 requests per minute for each authenticated user, on the admin:code:generation bucket that Create gift codes also counts against.
Revoke gift codes
Section titled “Revoke gift codes”POST/v1/admin/gift-codes/revokeRevokes unredeemed gift codes so that they can no longer be read or redeemed. Requires gift_codes:revoke. A redeemed code is left unchanged, so revocation never takes back entitlement a code has already granted.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| codes1 | array[string] | The codes to revoke (1-100 entries, each 1-32 characters) |
1 A code repeated in the array is handled once
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| revoked | array[string] | The codes that can no longer be redeemed, including codes an earlier request revoked, in request order |
| already_redeemed | array[string] | The codes left unchanged because they were already redeemed, in request order |
| not_found | array[string] | The codes that do not exist, in request order |
{ "revoked": ["aB3dEfGhIjKlMnOpQrStUvWxYz012345"], "already_redeemed": ["Zy9XwVuTsRqPoNmLkJiHgFeDcBa543210"], "not_found": []}Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | Every code was classified |
| 400 | error response | The body fails validation, returned as INVALID_FORM_BODY |
| 4031 | error response | The account does not hold admin:authenticate, does not hold gift_codes:revoke, or the instance is self-hosted |
1 Returned as MISSING_PERMISSIONS without admin:authenticate, as MISSING_ACL with that but without gift_codes:revoke, and as FEATURE_NOT_AVAILABLE_SELF_HOSTED on a self-hosted instance with the everyone premium mode
Side effects
Section titled “Side effects”Revocation and redemption are both conditional writes on the code’s version, so a code is never both revoked and redeemed: whichever write lands first wins. Get gift and Redeem gift answer a revoked code with 404 UNKNOWN_GIFT_CODE.
A failed request can leave earlier codes of the array revoked without returning them. Repeating the request is safe: a code that is already revoked is reported as revoked again and keeps its original revocation time.
The operation records one Admin audit entry with action revoke_gift_codes, target type gift_code, target ID 0, and metadata keys count, revoked, already_redeemed, and not_found, each holding a number of codes. The codes are not recorded. It emits no Gateway Dispatch.
Rate limit
Section titled “Rate limit”30 requests per minute for each authenticated user, on the admin:code:generation bucket that Create gift codes also counts against.