# Store promotion giveaway widget generator

Design, preview and export a self-hosted wheel, scratch card or mystery box. Local demos or merchant API results; no hosted prize service.

> Canonical page: https://elysiatools.com/en/tools/store-promotion-giveaway-widget-generator

- **Category:** Design

- **Keywords:** Store promotion giveaway widget generator, Lucky wheel, Scratch card, Mystery boxes

## Overview

## Campaign studio

Design, preview and export a self-hosted wheel, scratch card or mystery box. Local demos or merchant API results; no hosted prize service.

- Component: Lucky wheel / Scratch card / Mystery boxes
- Theme: Coastal minimal / Candy pop / Retro arcade / Midnight gold / Festival paper / Garden sketch

### Result source

Local draws are editable demonstrations, not secure prize allocation. Public offers in exported code are visible to visitors. No stock, identity or repeat-entry protection is provided.

Your server owns authentication, odds, inventory, eligibility and idempotency. Never put secret keys in this editor. Preview never calls your endpoint.

### Merchant API integration guide

This is an interface contract, not an Elysia draw service. Implement POST /api/draw on your server, set the same campaign ID and prize IDs there, then enter that endpoint here. Download and host the files on HTTPS to test real draws; the editor only simulates them.

#### Request · POST application/json

The widget sends only version, campaignId and a random 32-character hexadecimal requestId. It sends no customer ID, probabilities or API key. The server must identify the participant independently; requestId is not a login credential.

```json
{
  "version": 1,
  "campaignId": "summer-boutique",
  "requestId": "0123456789abcdef0123456789abcdef"
}
```

#### Success · 200 application/json

Echo requestId exactly. prizeId must match a configured prize, including a no-prize entry. Optional: receiptId (≤200 characters), claim.code (≤300), claim.url (HTTPS, ≤2048). Omit unused fields instead of sending null. The response has no data/result wrapper and must be ≤16 KiB. A failed draw is not a no-prize result.

```json
{
  "requestId": "0123456789abcdef0123456789abcdef",
  "prizeId": "p1",
  "receiptId": "draw_2026_001",
  "claim": {
    "code": "SAMPLE-ONLY",
    "url": "https://shop.example/redeem"
  }
}
```

Configured prize IDs:

- `p1`: 10% off
- `p2`: Free shipping
- `p3`: Mystery gift
- `p4`: Maybe next time

Prefer hosting the widget and /api/draw on the same origin (scheme + host + port), using a server-side reverse proxy if needed. Relative paths resolve against the widget page, not the parent shop page. fetch uses credentials: same-origin; only same-origin cookies are sent. No Authorization header or custom headers are configurable. Cross-origin endpoints need CORS for the widget origin and OPTIONS for POST + Content-Type; cross-origin cookies are not sent. A static HTML file alone cannot implement authenticated draws. Third-party iframe cookie restrictions can still affect sessions.

The backend must authenticate participants, validate Origin/CSRF and campaign eligibility, enforce entry limits and rate limits, choose prizes using server-owned odds, and reserve stock and save the outcome in one transaction. Persist idempotency by participant + campaignId + requestId, returning the same outcome on retries. Enforce redemption and expiry server-side. Never trust browser odds, IDs or claim codes as proof of entitlement; never put secrets in this editor or exports.

Reject requests with an appropriate non-2xx status (for example 401/403/409/429/503). The widget shows a generic unconfirmed-result message, not the server error text. It times out after 15 seconds and rejects redirects, invalid JSON, mismatched requestId, unknown prizes and unsafe claim URLs. Manual retry reuses the pending ID only on this page; reloading creates a new ID, so entry limits must be persistent. There is no automatic retry or local-prize fallback.

Offline appearance preview stays live while API or hosting fields are incomplete. Complete the highlighted fields to export; invalid prize or style fields keep the last valid preview.

### Export and embed

HTML / CSS / JavaScript / JSON. Host the exported files on your HTTPS site, then paste that page URL here. This tool does not publish or host campaigns.

Optional images load from their HTTPS hosts in visitors’ browsers. No images or API keys are stored by this editor.

Equal-size sectors are visual only; listed probabilities determine local demo results. In API mode, the server decides.

## Inputs

- **Configuration JSON** (textarea)

## When to use

- You want to launch an interactive giveaway on your storefront without relying on third-party hosted prize services.
- You need to test campaign visual themes, prize distributions, and wheel animations locally before going live.
- Your backend engineers require a lightweight, embeddable frontend widget that connects directly to a custom POST /api/draw endpoint.

## How it works

- Define your campaign identity, theme colors, widget type (wheel, scratch card, or mystery boxes), and configured prize lists in the JSON editor.
- Choose between local evaluation for rapid testing or API mode to delegate prize allocation, authentication, and inventory validation to your own server.
- Preview the interactive component live within the browser while visual and layout properties update instantly.
- Export the structured JSON configuration alongside HTML, CSS, and JavaScript files to host directly on your HTTPS storefront origin.

## Use cases

- Creating an on-site seasonal spin-the-wheel giveaway to boost visitor engagement and offer discount coupon codes.
- Integrating a gamified mystery box reveal on an e-commerce checkout success page backed by internal order rewards logic.
- Mocking and previewing interactive scratch card UI themes before integrating real reward redemption endpoints.

## Frequently asked questions

### Does this tool host or manage promotional prize inventory?

No. The generator exports self-hosted frontend code; all prize allocation, inventory deduction, and entitlement checks remain entirely on your backend server.

### What is the difference between local mode and API mode?

Local mode picks prizes inside the browser using configured probability values for testing, whereas API mode calls your POST /api/draw endpoint for server-authoritative outcomes.

### What data does the widget transmit to the backend endpoint?

In API mode, it sends a POST request containing only the version integer, campaignId string, and a random 32-character hexadecimal requestId.

### Can I configure custom HTTP authorization headers for the API request?

No. The widget uses same-origin fetch credentials, meaning authorization should rely on same-origin session cookies handled via a reverse proxy.

### What format must the backend draw response follow?

Your endpoint must return HTTP 200 with an unnested JSON body echoing the exact requestId and matching a configured prizeId, with optional receiptId and claim fields.

## Related tools

- [Color Token Cascade Generator](https://elysiatools.com/en/tools/color-token-cascade-generator): Turn one primary hex color into a full design-token cascade with primary, accent, neutral, semantic tokens, CSS variables, and Style Dictionary JSON
- [Image Palette to Design Tokens](https://elysiatools.com/en/tools/image-to-design-tokens): Extract a dominant color palette from an image (k-means clustering), then export it as CSS variables, SCSS variables, a Tailwind config, or JSON design tokens — with named colors and an auto-generated shade scale for each
- [API Request Code Snippet Generator](https://elysiatools.com/en/tools/api-request-code-snippet-generator): Generate cURL and common language code snippets from a request URL, method, headers, query parameters, and body
- [CSV to Database Migration Planner](https://elysiatools.com/en/tools/csv-to-database-migration-planner): Infer a relational schema from CSV data and generate create-table plus ALTER migration plans for PostgreSQL, MySQL, SQLite, or SQL Server
- [Fitness Workout PDF Generator](https://elysiatools.com/en/tools/fitness-workout-pdf-generator): Generate a printable workout-plan PDF from JSON or CSV data with exercise tables, progress boxes, and optional QR video links
- [GitHub Profile README Studio](https://elysiatools.com/en/tools/github-profile-readme-studio): Generate a complete GitHub profile README — banner, stats tiles, contribution heatmap, 3D contribution skyline and project cards — baked once into static, themeable SVG assets. No badge services that can go down; commit the SVGs next to your README and the profile never breaks.
- [OpenAPI to Postman Collection](https://elysiatools.com/en/tools/openapi-to-postman-collection): Turn an OpenAPI 3.x or Swagger 2.0 spec (JSON/YAML) into an importable Postman Collection v2.1.0 with folders, variables, auth and example responses.
- [OpenAPI to TypeScript Generator](https://elysiatools.com/en/tools/openapi-to-typescript-generator): Convert OpenAPI or Swagger JSON/YAML specs into TypeScript API types, request payloads, and response models with configurable output and naming styles

## Samples

- [Distributed Tracing Samples](https://elysiatools.com/en/samples/distributed-tracing-samples): Comprehensive distributed tracing examples using Jaeger, OpenTelemetry, and other modern observability tools for microservices architecture
- [AWS EventBridge Samples](https://elysiatools.com/en/samples/eventbridge-samples): AWS EventBridge examples including event buses, rules, targets, schema registry, custom events, and cross-account event routing for serverless event-driven architecture
- [JWT Samples](https://elysiatools.com/en/samples/jwt-samples): Comprehensive JWT examples from basic token structure to advanced security implementations
- [PDF Samples](https://elysiatools.com/en/samples/pdf-samples): Generated PDF samples from tools dated 2026-02-01 to 2026-02-10

## Related content

- [Self-Hosted Giveaway Widget Review and Embed Handoff](https://elysiatools.com/en/hubs/self-hosted-giveaway-widget-review-and-embed-handoff): Review giveaway configuration, merchant response samples, contrast and responsive layouts, then hand off identified widget files with browser acceptance evidence.