Giveaways — Bot Docs

Required Plan Giveaways require the giveaways feature on your subscription.

Starting a Giveaway

Free plan vs Pro Giveaways work even without an active plan. On the Free tier you can run up to 5 giveaways per 30 days with every core feature — eligibility & requirements, the full bonus/weighting system, winner roles, cooldown, DM winners, ghost ping, start ping and scheduling. Pro (an active trial or paid plan) removes the monthly limit and unlocks the customization extras: embed appearance (images, thumbnail, author, footer, custom fields), custom button/reaction icons and the prize-claim ticket system.

Run /giveaway create in Discord — a short modal asks for the prize, duration, winners, description and optional schedule, then an ephemeral panel lets you pick the channel, eligibility roles, requirement numbers, toggles and winner role before launching. A More button on that panel opens an advanced view for the donor/sponsor, entry method (button vs. reaction), role-bonus & bonus-stacking toggles, cooldown, an optional ghost-ping for new members, and an Icons modal for the message's custom emoji. Or open Dashboard → Giveaways → New Giveaway for the full form. Only the prize and duration are required.

Both surfaces now cover the same core setup — eligibility, requirements, toggles, bonuses, winner role, scheduling, donors, entry method, button icons, claim window and cooldown. Only the richer embed appearance (author line, footer, custom fields, thumbnail & image — see Embed Appearance) and the custom winner / end / denial messages remain dashboard-only.

Create the channel on the fly Don't have a giveaways channel yet? In the dashboard's Channel field, click “Create a new channel” to make one — give it a name and optionally drop it inside a category — without leaving the page. It's created immediately and selected for this giveaway. In Discord you can also point a giveaway at any channel from the config panel's channel picker.

Option	Required	Description
`prize`		What you're giving away — the embed title (max 200 chars).
`duration`		How long to run (1 minute up to 12 months) — a free-form duration using `m` minutes, `h` hours, `d` days, `w` weeks, `mo` months, e.g. `30m`, `12h`, `7d`, `2w`, `3mo` or combined like `1d12h`.
`winners`	—	Number of winners (1–50, default 1).
`channel`	—	Where to post. In Discord it defaults to the current channel and can be changed on the config panel; on the dashboard pick it from a dropdown.
`schedule start`	—	Schedule the giveaway to begin later. On the dashboard, pick the exact start with a calendar & time picker (shown in your local time zone, with a live preview of when it will publish and how far away that is). From the slash command the create modal’s Schedule start field takes a relative delay — e.g. `2h` or `1d` — leave it blank to start now. Either way it posts immediately as “Scheduled” and opens automatically at the chosen time.
`description`	—	Extra text inside the embed.
`donor`	—	Who donated/sponsored the prize. Shown as “Donated by” in the embed; donors are blocked from entering and can never win. Add one or more donors from the dashboard (a searchable member picker) or from the More panel of the Discord create flow.

Searchable pickers On the dashboard you don't need to copy IDs. The Donor / Sponsor field is a type-to-search member picker that lets you add one or more members (search by name, pick from avatars, each appears as a removable chip), and the eligibility Required / Blocked role fields are searchable role pickers. Bot-managed (integration) roles are hidden, since they can't be assigned manually.

Scheduling a giveaway Use Schedule start in the New Giveaway dialog to pick the exact date and time the giveaway should publish — leave it empty to start right away. Times are entered and previewed in your own time zone, and the giveaway message shows the start time as a Discord timestamp so every member sees it in theirs. A scheduled giveaway sits in the Scheduled state until its time arrives, then opens for entries on its own. You can reschedule it (its run length is kept) or cancel it any time before it goes live from Edit on its card.

Entry Requirements

Requirements are validated in real-time on entry. Role gates are always enforced; the metric checks below combine with AND (meet all) or OR (meet any), so you can build combos like “100 messages OR 2 hours in voice”.

Requirement	Description
`required_role`	Only members with this role may enter.
`restricted_role`	Members with this role are blocked — and auto-removed if they gain it after entering.
`min_messages`	Minimum messages sent in the server (tracked by leveling).
`min_voice_minutes`	Minimum voice time in the server.
`in_voice`	Must currently be in a voice channel — entries are auto-removed if they disconnect.
`min_account_age`	Discord account must be at least N days old.
`min_level`	Minimum leveling level (requires the leveling feature).
`min_invites`	Must have invited at least N members.
`require_verified`	Must hold the captcha verified role.

Auto-removal If a member's status changes so they no longer qualify — they leave voice, gain a blocked role, or lose a required role — their entry is removed automatically and the entry count updates.

Check your requirement status Members can see exactly where they stand before entering. Click the 📋 Requirements button on the giveaway message (shown whenever a giveaway has requirements) for a private breakdown with live progress:

✅ Completed — requirements you already meet.
❌ Remaining — what's still left, with progress counters (e.g. 45/100 messages).
📜 All Requirements — the full list, plus a note on whether you need all (AND) or any (OR) of the metric checks.

Bonus Entries (Weighting)

A member's chance is proportional to their total entries: base 1 plus any bonuses, stacked together.

Role bonuses — grant extra entries per role (e.g. VIP +5, Booster +10). Stackable across multiple roles.
Booster bonus — a flat bonus for server boosters.
Manual / programmatic bonus — grant up to 1000 extra entries to a specific user via the ⚙️ Manage → Bonus Entries panel or from the dashboard.

Winners, Backups & Rerolls

Selection is a weighted random draw with no duplicate winners. Each candidate's eligibility is re-checked at the moment of selection — anyone who left or no longer qualifies is skipped, and backups are drawn for replacement.

To end a giveaway early or reroll its winners, click ⚙️ Manage on the giveaway message in Discord (managers only): End Now draws winners immediately, and once ended a Reroll Winners button redraws everyone. The same actions are available from Dashboard → Giveaways.

When a reroll runs, the bot posts a fresh congratulations announcement in the giveaway's channel — e.g. “🎉 Congratulations @user! You won the reroll for Prize!” — pinging the new winner(s) and including a Jump to Giveaway button (plus the Claim Reward button when prize-claim tickets are enabled).

Tag the host: by default the announcement also tags the giveaway's host. Toggle this server-wide under Giveaways → Defaults → “Tag the host on reroll announcements”.

Winner Roles

Automatically grant winners a Winner role when a giveaway ends — handy for showcasing winners, gating a prize-claim channel, or pinging them. Configure it per giveaway (create/edit modal) or set a server-wide default. Choose one of two modes:

Mode	Description
None	No winner role is assigned (default).
Shared role	Every winner receives the same predefined role you pick. Bot-managed roles are hidden, and the bot can only assign roles below its own highest role.
Auto-create per giveaway	The bot creates a unique role for that giveaway, assigns it to the winners, and deletes it automatically once everyone has claimed or the time limit passes.

When the role is removed. A winner keeps the role until either:

The prize is claimed — when prize-claim tickets are on, closing the winner's claim ticket releases their role. (For a per-giveaway role, once every winner has claimed, the role is deleted.)
The time limit elapses — set “Remove role after” to a duration (1 hour up to 30 days) and the role is stripped automatically. Choose Until claimed / manual to keep it until claimed or removed by hand.

Survives restarts & rerolls Assignment and removal are handled by the bot, so they work whether a giveaway ends from a command or the dashboard. Removal timers are restored on restart, and a reroll moves the role from the replaced winner to the new one automatically.

Managing Running Giveaways

Manager actions live on the ⚙️ Manage panel — click it on any giveaway message in Discord (visible to giveaway managers only) or use Dashboard → Giveaways. The panel also lets you edit the prize text, requirements and toggles in place.

⚙️ Manage action	Description
Pause	Pause entries; the remaining time is preserved.
Resume	Resume a paused giveaway.
Extend	Add more time (enter a duration like `1h30m`).
Duplicate	Clone an existing giveaway's settings into a new one.
Cancel	Cancel with no winners.
Bonus Entries	Grant a user up to 1000 extra entries.

Managers can also drive the lifecycle straight from slash commands (same permission as the ⚙️ Manage panel — Manage Server or a giveaway manager role):

Command	Description
`/giveaway list`	List active, paused, and scheduled giveaways.
`/giveaway end <id>`	End an active giveaway now and draw winners.
`/giveaway reroll <id> [user]`	Reroll all winners of an ended giveaway, or just the given winner.
`/giveaway pause <id>` / `resume <id>`	Pause or resume a giveaway (remaining time is preserved).
`/giveaway extend <id> <duration>`	Add more time, e.g. `1h30m`, `2w`, `3mo` (up to 12 months).
`/giveaway cancel <id>`	Cancel a giveaway with no winners.

Prefer text commands? The same lifecycle controls are available as prefix commands — use your server prefix (default !) or @mention the bot, with the giveaway command (aliases gw / ga):

Prefix command	Description
`!giveaway list`	List active, paused, and scheduled giveaways (open to everyone).
`!giveaway end <id>`	End an active giveaway now and draw winners.
`!giveaway reroll <id> [@user]`	Reroll all winners, or just the mentioned winner.
`!giveaway pause <id>` / `resume <id>`	Pause or resume a giveaway (remaining time is preserved).
`!giveaway extend <id> <duration>`	Add more time, e.g. `1h30m`, `2w`, `3mo` (up to 12 months).
`!giveaway cancel <id>`	Cancel a giveaway with no winners.

Creating a giveaway needs the interactive panel, so it stays on /giveaway create and the dashboard — the prefix command covers the lifecycle controls only, gated by the same manager check (Manage Server or a giveaway manager role).

Members enter, leave, and check their status straight from the buttons on the giveaway message — no slash commands needed.

Prize Claiming & Notifications

Prize-claim tickets — enable per giveaway so winners click Claim Prize on the ended message to open a private channel with your support role.
Claim window — set how long winners have to claim before the prize is forfeited. Choose a duration measured from the moment the giveaway ends (5 minutes up to 1 week) or a fixed calendar deadline (date & time in your local zone), or leave it Unlimited for no deadline. When the window passes unclaimed, any winner role is released and — for an auto-created per-giveaway role — the role is deleted. Configurable from the dashboard (duration or specific date/time) and from the Discord create flow (duration).
Auto-DM — winners are direct-messaged when selected (toggleable).
Ghost-ping new members — optionally draw fresh joiners to a live giveaway: when a member joins the server, the bot mentions them in the giveaway's channel, then deletes the ping about a second later so they get the notification without leaving clutter behind. It only ever pings the joining member (never @everyone or existing members) and is captcha-aware — if captcha gates the member, the ping is held until they verify and can actually see the channel, just like the channel join ghost ping. You can set a custom ghost-ping message (shown after the mention); leave it blank to use the default “Don't miss the giveaway for <prize>!”. Toggle it — and enter the message — per giveaway from the dashboard New Giveaway form (the message field appears once the toggle is on) or the More → Cooldown, Emoji & Ghost Ping modal of the Discord create flow; it applies while the giveaway is active.
Entry method — entries are collected via a 🎉 Enter button by default, or by reacting with an emoji if you switch the giveaway to reaction entry (on the dashboard, or from the More panel of the Discord create flow).
Custom button icons — give the giveaway your own flavour by swapping in server emoji for the Enter button, the reaction emoji (reaction method), and the Requirements and Participants buttons. Pick from a server-emoji picker on the dashboard, or open the More → Icons modal in the Discord create flow. Each icon falls back to its default (🎉 / 📋 / 👥) if left blank, and a custom emoji that isn't available in the posting server — e.g. a duplicated giveaway moved to another guild, or an emoji lost to a boost-level downgrade — gracefully reverts to the default.
Live embeds — a relative countdown and real-time entry count, with Enter, Requirements and Participants buttons (the Requirements button appears only when the giveaway has entry rules; clicking Enter again lets a member leave). When bonus entries are configured, an Extra Entries section lists each bonus role and the entries it grants.
Participants list — the Participants button opens a private, paginated leaderboard (10 per page) ranked by entry count, opening on and highlighting the viewer's own position.

Embed Appearance

Beyond the automatic giveaway body (prize, winners, entries, countdown), you can customise how the embed looks from Dashboard → Giveaways — per giveaway under Embed Appearance in the create/edit form, or server-wide under Defaults. A live preview on the create page shows your changes as they'll appear in Discord.

Setting	Description
Accent colour	The embed's left-edge colour.
Author line	A small name + optional icon shown above the title.
Footer	Custom footer text + icon. Blank uses the default “Giveaway · Ends”.
Thumbnail	A small image in the top-right of the embed.
Main image	A large image across the bottom of the embed.
Custom fields	Up to 5 extra name/value fields appended to the embed.

Images: paste or upload Every image field accepts an https:// URL or a direct upload (the file is re-hosted on Discord's CDN for you). Leave any appearance field blank to inherit the server default set under Defaults. Embed appearance, custom winner/end/denial messages and custom fields are configured from the dashboard.

Remembers your last-used appearance When you launch a giveaway, the dashboard quietly remembers the Embed Appearance you used — author line, footer, thumbnail, main image and custom fields — and pre-fills them the next time you open New Giveaway, so you don't re-enter the same look every time. This is saved in your browser, per server (it never touches the server-wide Defaults, so a one-off custom giveaway won't overwrite them), so it follows the browser you create from rather than your account. The prize-specific description is intentionally not remembered, and launching with the appearance fields cleared resets what's remembered. Prefer a look that applies everywhere and across devices? Set it under Defaults instead.

Anti-Abuse & Logging

Enable anti_alt to score accounts on age, avatar, server tenure and username patterns; anything over the threshold is blocked. Per-giveaway cooldowns throttle entry spam, and duplicate entries are prevented at the database level.

Every action — creation, edits, entries and removals, winner selection, rerolls, ticket creation and staff actions — is written to the giveaway audit log and mirrored to your configured log channel.

Data Retention

Giveaway data is kept for 30 days after a giveaway finishes, then permanently deleted. A daily cleanup removes every giveaway that ended or was cancelled more than 30 days ago, along with all of its associated records:

Entries — who entered and their weighted entry counts.
Winners & backups — the drawn winners, backups, and reroll history.
Bonus entries — manual / programmatic per-user bonuses.
Prize-claim tickets and invite/referral attribution for that giveaway.
Audit log — a giveaway's log entries are kept for its whole run and removed together with it, 30 days after it finishes (so a months-long giveaway keeps its full history until then).

What this means Only finished giveaways are affected — active, scheduled, and paused giveaways are never touched, and the 30-day window only starts counting once a giveaway ends or is cancelled. After deletion the data is gone for good, so export anything you want to keep (winners, entrant lists) before the window closes. The giveaway message left in your Discord channel is not removed — only the stored data is.

Server Defaults

Set guild-wide defaults under Dashboard → Giveaways → Defaults: log channel, manager roles, role/booster bonuses, anti-alt threshold, default cooldown, ticket category & support role, whether claim tickets and winner DMs are on by default, whether reroll announcements tag the host, the default winner-role mode, shared role and removal time, and a full default embed template (accent colour, author line, footer, thumbnail & image, and custom fields — see Embed Appearance). New giveaways inherit all of these unless overridden.