Bulk Awards

Bulk awards let you issue badges to hundreds or thousands of recipients at once by uploading a CSV file. The process has four steps with built-in progress tracking, pause/resume, and error handling.

Overview

The bulk award process follows four steps:

1. Configure — select the badge and options
2. Upload — prepare and upload your CSV file
3. Process — monitor progress as awards are created
4. Results — review outcomes and download reports

Step 1: Configure

1. Open the Bulk Awards page from the sidebar (its own route, separate from the Awards page).
2. Select the badge you want to award using the badge picker.
3. Optionally configure:
   • Issued On — the date to use for all awards (defaults to today)
   • Expires — optional expiration date for all awards
   • Send Email — whether to automatically email each recipient after their award is created
4. Click Next.

Step 2: Upload CSV

CSV Format

The CSV file must have a name column and an email column, with a header row. Header names are case-insensitive, and recipient_name / recipient_email are accepted as aliases for name / email.

name,email
Jane Smith,jane@example.com
John Doe,john@example.com
Maria Garcia,maria@example.com

Download Template

Click Download Template to get a blank CSV file with the correct headers. Fill it in with your recipients and upload it.

Upload

1. Click Upload CSV or drag and drop your file.
2. The file is validated before processing begins.

Validation Rules

Each row is validated as soon as the file is parsed:

• Name must be at least 5 characters
• Email must be a valid email address
• Empty rows are skipped

The preview table lists every row with a green check or a red reason. Invalid rows aren't a blocker — they're simply skipped, and the counter shows how many valid recipients will be processed (e.g. "18 valid recipients, 2 invalid (will be skipped)"). You can proceed as long as at least one row is valid; there's no need to fix and re-upload first.

3. Click Next to begin processing.

Step 3: Processing

Once processing starts, you see a progress bar and live counters:

• Progress bar — the percentage of rows processed
• Created — how many awards have been created
• Failed — how many rows have failed
• Remaining — how many rows are still queued

Live Created, Failed, and Pending tables fill in beneath the bar as the batch runs.

Pause and Resume

• Click Pause to temporarily stop processing. No new awards are created while paused.
• Click Resume to continue from where you left off.

Cancel

• Click Cancel to stop processing entirely. Awards already created are kept.

Error Handling

When a row fails for a row-specific reason (e.g. an invalid value the backend rejects):

• The error is recorded against that row
• Processing continues to the next row automatically
• Failed rows are collected for the results step, with their error text shown in the on-screen failures table

Rate-limited rows are retried automatically with a short back-off. A credits or quota error is different — rather than skipping ahead, the batch pauses so you don't burn through the rest of the file. A red "Insufficient credits" notice appears; top up or upgrade, then click Resume to continue from where it stopped.

Page Refresh Recovery

If you accidentally close the browser or refresh the page during processing, the bulk award session is recovered when you return. Progress resumes from where it stopped.

Step 4: Results

After processing completes (or is cancelled), the results screen shows four summary cards:

• Total — number of recipients in the batch
• Created — number of awards created
• Failed — number of rows that failed
• Skipped — recipients not processed (e.g. remaining rows after a cancel)

Below the cards, a Created table lists each new award with a link to view it, and a Failed table lists the failures with their error text.

Download Reports

• Download Results CSV — every row in the batch, with columns row, name, email, status, award_url (the award URL is filled in for created rows).
• Download Failures CSV — the failed rows only, with columns name, email, error.

Retry Failures

If some rows failed, click Retry Failures. This starts a fresh pass over just the failed recipients — no need to re-upload a CSV. It's handy after fixing a transient issue such as topping up credits following a paused batch.