API Reference

Instant Win

Manage instant win games and record plays

Instant Win

Instant win games are slim contests with a server-side prize draw. Visitors play first; they only enter an email when claiming a win.

mechanic, layout, and entryLimit are set at create time and cannot be changed later.

List Games

GET/api/v1/instant-win-games
Public or Private API Key

Query Parameters

slugstring optional

Filter by preset: `spin-to-win`, `scratch-and-win`, `mystery-box`, `advent-calendar`, `plinko`, `slot-machine`, `golden-egg`, or `claw-machine`. Retired presets (`trade-show-prize-wheel`, `daily-login-game`, `coupon-roulette`, `in-store-kiosk`) are still accepted as filters for existing games.

pagenumber optional default: 1

Page number

limitnumber optional default: 20

Items per page (1-100)

Get Game

GET/api/v1/instant-win-games/:gameId
Public or Private API Key

Returns config, tiers, odds, inventory (quantity), and unique-code counts.

Create Game

POST/api/v1/instant-win-games
Private API Key Required

Request Body

slugstring required

Preset identifier: `spin-to-win`, `scratch-and-win`, `mystery-box`, `advent-calendar`, `plinko`, `slot-machine`, `golden-egg`, or `claw-machine`

titlestring required

Game title

mechanicstring required

`wheel`, `scratch`, `box`, `advent`, `plinko`, `slots`, `egg`, or `claw`

layoutstring required

`default` or `fullscreen`

entryLimitstring required

`none`, `daily`, or `device`

tiersarray required

At least two tiers. Odds must sum to 100. Non-miss tiers need a `redeemCode` or `redeemUrl`.

publishAsstring required

`landing` or `embed`

embedUrlstring optional

Required when publishing as a widget

Request

bash
curl -X POST https://blitzrocket.com/api/v1/instant-win-games \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "spin-to-win",
    "title": "Summer wheel",
    "mechanic": "wheel",
    "layout": "default",
    "entryLimit": "daily",
    "publishAs": "landing",
    "tiers": [
      { "id": "win", "name": "20% off", "oddsPercent": 20, "deliveryType": "code", "redeemCode": "SUMMER20" },
      { "id": "miss", "name": "Try again", "oddsPercent": 80, "isMiss": true }
    ]
  }'

Update Game

PUT/api/v1/instant-win-games/:gameId
Private API Key Required

You can change title, description, tiers, publish mode, and status. Attempts to change mechanic, layout, or entryLimit are ignored.

Delete Game

DELETE/api/v1/instant-win-games/:gameId
Private API Key Required

If the game has claimed entries, pass ?force=true or the API returns 409.

Play

POST/api/v1/instant-win-games/:gameId/play
Public or Private API Key

Runs the weighted draw. Wins are reserved for 24 hours. Fulfillment is hidden until claim.

Request Body

playCookiestring optional

Device cookie from a previous play. Store and reuse the returned `playCookie`.

Response

json
{
  "success": true,
  "data": {
    "playId": "play_abc",
    "playCookie": "a1b2c3d4",
    "alreadyPlayed": false,
    "result": {
      "id": "win",
      "name": "20% off",
      "isMiss": false,
      "color": "#F59E0B"
    }
  }
}

entryLimit of daily or device returns 403 if the cookie or IP has already played.

Claim

POST/api/v1/instant-win-games/:gameId/plays/:playId/claim
Public or Private API Key

Creates an entry, marks the play claimed, and emails the prize.

Request Body

emailstring required

Winner email address

playCookiestring optional

Same cookie returned by play

Response

json
{
  "success": true,
  "data": {
    "alreadyClaimed": false,
    "prizeName": "20% off",
    "couponCode": "SUMMER20",
    "redeemUrl": null
  }
}

List Plays

GET/api/v1/instant-win-games/:gameId/plays
Private API Key Required

Paginated play log with status (pending, claimed, miss, expired), tier, and claimed email.