Skip to main content
The gifting flow turns a gift-offer purchase into an on-stream giveaway. While a creator is live, a supporter buys a product as a gift to the chat; Fourthwall mints the gift(s) and notifies your app; your app collects viewers as entrants, picks the winner(s), and sends each winner a link to redeem their gift for free. The key thing to understand is who owns what:
  • Fourthwall mints the gifts. They’re created on the purchase and arrive on the GIFT_PURCHASE webhook, each with its own gift id (gft_…). Your app never creates a giveaway.
  • Your app runs the draw. It collects entries from the stream, picks the winner(s), and hands each winner the redemption link for their gift. There’s no “finish” call — the gift link is the handoff back to Fourthwall.
A complete, runnable reference implementation lives in fourthwall-examples/streaming-gifting — a Platform App that does exactly this end to end, with a mock chat for entries and a mock winner-login for redemption.

​
How It Works

  1. A supporter buys a gift offer on the storefront while the creator is live. (Gift offers are only purchasable while the shop is live.)
  2. Fourthwall mints the gifts and delivers a GIFT_PURCHASE webhook. The payload carries the minted gifts as gifts[], each with a gft_… id.
  3. Your app opens a short entry window (e.g. the creator’s configured entry-time limit).
  4. Viewers opt in — typically by typing !enter in chat. Your app collects their userId/userName.
  5. When the window closes, your app picks up to one winner per gift at random.
  6. Your app sends each winner a link to their gift’s redemption page (keep the links private — only hand each one to the winner you picked).
  7. The winner opens the link and claims the prize on the storefront.

​
1. Configure the gifting rules

A shop’s gifting rules — whether gifting is enabled, the entry-time limit, the shipping policy, and which products are giftable — live on its gifting config: Get gifting config and Update gifting config (GET/PUT /open-api/v1.0/gifting/config). Most integrations surface these as settings in the app so the creator controls them; the write operates on the app’s OPEN_API gifting slot.
Gifting has a single slot per shop. If another integration (e.g. a Twitch app) already owns it, the config write is rejected — surface that conflict to the creator instead of overwriting silently.

​
2. Subscribe to the webhook

Create a webhook for GIFT_PURCHASE — this is the trigger that opens a draw. (Add PLATFORM_APP_DISCONNECTED too if you want to know when the creator uninstalls.)
See Managing Webhooks via API for the complete setup including signature verification. You can also subscribe through the dashboard.

​
3. Handle the gift purchase

When GIFT_PURCHASE arrives, read the gifts off the payload and open an entry window. Each entry in gifts[] is one prize, with a gft_… id you’ll redeem later:
The same shape is available on demand from Get Gift Purchase if you need to re-read it.

​
4. Collect participants from your stream

This part lives in your app, not in the Fourthwall API. A typical flow:
  • Subscribe to Twitch EventSub channel.chat.message (or Discord, or a web form).
  • Watch for an !enter command from viewers while the window is open.
  • Store { userId, userName } for each entrant in a deduped set.
  • Close the window when the entry timer expires.
How you collect entries is up to you — the only thing Fourthwall needs is that you decide who won. Pick the winner(s) yourself — one per gift — and send each the redemption page for their gift. The link is the shop’s storefront URL plus the gift id:
Keep these links private; hand each one only to the winner you selected (the gift id is the bearer token). The winner opens the link, picks a variant if needed, and checks out the prepaid gift — no further API call from your app.
The reference example gates this with a small “enter your chat name” redeem page that reveals a winner’s link only after they identify themselves — a stand-in for authenticating the winner (e.g. a Twitch login) before exposing the gift link.

​
OAuth scopes

If your integration uses OAuth instead of API keys, request giveaway_write + webhook_write + offer_read. See App OAuth for the full app authorization flow.

​
Reference

streaming-gifting example

A complete runnable Platform App for this flow

Get Gift Purchase

GET /gift-purchase/{id} — the gifts[] payload

Gifting config

GET/PUT /gifting/config — the gifting rules

Managing Webhooks

Subscribe to GIFT_PURCHASE + verify signatures

App OAuth

Request giveaway_write for gifting