> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fourthwall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gifting

> Turn gift-offer purchases into on-stream giveaways — collect viewers as entrants, pick a winner, and send them a link to redeem their gift

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.

<Tip>
  A complete, runnable reference implementation lives in [`fourthwall-examples/streaming-gifting`](https://github.com/FourthwallHQ/fourthwall-examples/tree/main/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.
</Tip>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Shop
    participant Fourthwall
    participant App as Your App
    participant Stream as Stream chat
    participant Winner

    Shop->>Fourthwall: ① Supporter buys a gift offer (while live)
    Fourthwall->>App: ② GIFT_PURCHASE webhook (carries gifts[].id)
    App->>App: ③ Open an entry window
    Stream->>App: ④ Viewers enter (e.g. !enter)
    App->>App: ⑤ Pick winner(s)
    App->>Winner: ⑥ Send their gift redemption link
    Winner->>Fourthwall: ⑦ Redeem at <shop>/gifts/{giftId}
```

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](/api-reference/platform/gifting/get-gifting-config) and [Update gifting config](/api-reference/platform/gifting/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.

<Tip>
  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.
</Tip>

## 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.)

```bash theme={null}
curl -u "your_username:your_password" \
  -X POST "https://api.fourthwall.com/open-api/v1.0/webhooks" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/fourthwall",
    "allowedTypes": ["GIFT_PURCHASE"]
  }'
```

See [Managing Webhooks via API](/webhooks/api-management) for the complete setup including signature verification. You can also subscribe through the [dashboard](https://my-shop.fourthwall.com/admin/dashboard/settings/for-developers?redirect).

## 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:

```json theme={null}
{
  "type": "GIFT_PURCHASE",
  "data": {
    "id": "giv_…",
    "offer": { "name": "Logo Tee" },
    "quantity": 1,
    "username": "supporter_handle",
    "gifts": [
      { "status": "AVAILABLE", "id": "gft_HgITVrX8SFK7fFuEyAbOA" }
    ]
  }
}
```

The same shape is available on demand from [Get Gift Purchase](/api-reference/platform/gift-purchases/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.

## 5. Send each winner their redemption link

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:

```
https://<shop-domain>/gifts/{giftId}
```

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.

<Tip>
  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.
</Tip>

## OAuth scopes

If your integration uses OAuth instead of API keys, request `giveaway_write` + `webhook_write` + `offer_read`. See [App OAuth](/guides/oauth) for the full app authorization flow.

## Reference

<CardGroup cols={2}>
  <Card title="streaming-gifting example" icon="github" href="https://github.com/FourthwallHQ/fourthwall-examples/tree/main/examples/streaming-gifting">
    A complete runnable Platform App for this flow
  </Card>

  <Card title="Get Gift Purchase" icon="gift" href="/api-reference/platform/gift-purchases/get-gift-purchase">
    `GET /gift-purchase/{id}` — the `gifts[]` payload
  </Card>

  <Card title="Gifting config" icon="sliders" href="/api-reference/platform/gifting/get-gifting-config">
    `GET`/`PUT /gifting/config` — the gifting rules
  </Card>

  <Card title="Managing Webhooks" icon="bell" href="/webhooks/api-management">
    Subscribe to `GIFT_PURCHASE` + verify signatures
  </Card>

  <Card title="App OAuth" icon="key" href="/guides/oauth">
    Request `giveaway_write` for gifting
  </Card>
</CardGroup>