Contents

Drops Guide

We've revised the Developer Services Agreement to include subscription-based Twitch Drops, and reorganized related Drops information. Game developers who currently or plan to use Twitch Drops should take a moment to review the revised Agreement.

Introduction

Twitch Drops enables you as a game developer to grant in-game rewards to the Twitch community when streamers play your game. Twitch Drops brings the Twitch community closer to your game, ultimately helping you acquire new players or re-engage your existing player base.

Twitch tracks select viewer actions and watch activity for your games, then distributes rewards based on the Drop rules you define for participating channels when configuring your Drops campaign (e.g. watching your game for 60 minutes). Once a rule has been satisfied by the viewer, they will be able to claim the Drops rewards and generate an entitlement. The Twitch Entitlements Service provides an easy-to-use interface to retrieve all viewers who earned rewards by participating in your campaigns so you can deliver the corresponding in-game items to your players.

Important Terms

Term Definition Example
Drops Campaign A collection of Drops that are distributed during a specified time period. Drops within a campaign can only be earned between the campaign’s start and end dates. “Super Soccer 2023 Launch”
Drop A collection of rewards distributed to viewers based on a Drop rule during the campaign time period. Limited Edition Soccer Balls
Drop Rule (i.e. milestone, requirement, etc) The conditions viewers must meet on participating channels in order to earn a drop. Watch for 60 minutes
Reward An in-game item that is granted by a Drops campaign owner to viewers who are entitled to it. Typically, these are either consumables (e.g. coins), items (e.g. skins), or keys (e.g. beta-access keys). “Ultimate Ball”
Benefit Benefit and Reward are interchangeable terms. Rewards are created in the Rewards Manager and are surfaced as Benefits in the API. "398dnb-9kdlsnm-dasdfk2-doandbo3-onbm21"

The above Benefit ID is the Reward ID of “Ultimate Ball”.
Entitlement A record of a viewer earning a specific Drop (and the rewards it contains). "fb78259e-fb81-4d1b-8333-34a06ffc24c0"
Campaign Status Campaigns can be set to one of these six states:

Disabled - The campaign is not visible on Twitch. Any fields within the campaign can be edited.

Test - The campaign is visible to Test viewers. Any fields within the campaign can be edited.

Upcoming - The campaign is enabled but the start time has not passed.

Live - The campaign is enabled and the present time is between the start and end time.

Expired - The campaign is removed from Twitch because the campaign end time has elapsed.

Expired Manually - The campaign is removed from Twitch because a campaign owner canceled it before its scheduled end.		 disabled

test

upcoming

live

expired

expired manually

Prerequisites and Setup

Once a developer within your Twitch developer organization sets up Twitch Drops, campaigns can be created and managed by anyone within the organization.

Organization and Game Setup

In order to use Twitch Drops, you must have a Twitch developer organization and have claimed your game that your Drop rewards will be associated with. For more information, see Organizations to get started.

Game ID

You will need the numerical Twitch game ID to use Drops. You can find your game ID by calling the Get Games API endpoint:

curl -H 'Client-Id: <your_client_id>' \
-H 'Authorization: Bearer <your access token>' \
-X GET 'https://api.twitch.tv/helix/games?name=<exact_game_name>'

Create a Twitch Application for Drops

Drops uses the Twitch API to inform your game’s identity and fulfillment services which Twitch viewers have authorized you to grant rewards to their associated game accounts. You can use the same Twitch application to authenticate Twitch users with your account services and to access the Entitlements API. To create a Twitch application, see the Get Started Guide for the Twitch API.

Whether you are creating a new Twitch application or using an existing one, you will need to identify which Twitch developer organization will be using the application for Drops from the application management page. Go to your Developer Applications listing page and click the “Manage” button for the application you will be using. On this application management page, use the “Organization” dropdown to select the appropriate organization.

New Application for Drops

Next, make sure the client ID of your Twitch application is associated with your games on the Drops Settings page. Look for the following button on the “Drops Campaigns” tab of the Developer Console for your organization.

Drops Settings button

Click the “Edit Details” button next to the game that will be using your Twitch application. Enter the Client ID of your Twitch application, which can be found on its application management page.

Account Linking

In order to claim in-game rewards, Twitch viewers will need to link their Twitch and game accounts.

In order to correctly link Twitch and game accounts:

  1. Ask viewers to log into your account system
  2. Ask viewers to authorize your Twitch application with their Twitch account
  3. Store the Twitch account <> game account mapping

Note: Allowing a user to authenticate with Twitch before your account login may result in the user thinking the account is connected when it is not!

Specifically, we recommend that you store the following information:

While account linking can be achieved in-game, we recommend hosting a webpage to let Twitch viewers link their accounts. You can add this URL to your campaign configuration so that Twitch can redirect your viewers to the correct account linking page.

Refer to the Twitch OAuth guide for more information and options regarding how to authenticate Twitch users to achieve account linking.

Entitlements Management

EventSub Subscription Type

EventSub is a third-party developer product that allows you to listen for real-time events. The drop.entitlement.grant subscription type sends a notification when an entitlement for a Drop is granted to a viewer. For detailed information regarding this EventSub topic, see Drop Entitlement Grant.

Get Drops Entitlements API endpoint

This endpoint retrieves entitlements that have been granted for a game, to a viewer, or both. For detailed information regarding this endpoint, see Get Drops Entitlements.

Update Drops Entitlements API endpoint

This endpoint updates the fulfillment status for a list of entitlements. For detailed information regarding this endpoint, see the Update Drops Entitlements documentation.

Tracking Entitlement Fulfillment Status

Generally, there are two approaches to tracking fulfillment status:

Twitch-owned Developer-owned
Retrieve entitlements that have been claimed (i.e. filter out entitlements that have already been fulfilled).

Using the API, update their status to fulfilled after granting the item in-game.		 Retrieve all entitlements and store them in your own database alongside their fulfillment status.

Update their status to fulfilled after granting the item in-game.

The following is the recommended integration flow:

  1. Register an EventSub subscription for your organization. You may choose to create a subscription at the individual game or campaign level.

Below is a sample organization-level subscription condition for EventSub. It requires your organization id, which is the universal unique identifier found in the URL when viewing your organization on the Twitch developer console.

"condition":
  {
    "organization_id": "cae0e125-0f7a-4072-b8bf-23d6aa4098a9",
  }

Below is a sample game-level subscription condition for EventSub. A “category_id” is synonymous with the game id mentioned earlier provided by the Get Games API endpoint.

"condition":
  {
    "organization_id": "cae0e125-0f7a-4072-b8bf-23d6aa4098a9",
    "category_id": "33214"
  }
  1. De-duplicate any entitlements sent to you over EventSub using the entitlement_id. It is possible for duplicate messages to be sent over EventSub in situations such as retries.
  2. When a user launches their game launcher, query the Get Entitlements API for all claims for the user with fulfillment_status = CLAIMED.
  3. Reconcile data that is received from EventSub as well as the Get Drops Entitlements API.
  4. Grant in-game items to the user.
  5. Update the fulfillment_status = FULFILLED on Twitch by using the Update Drops Entitlements API endpoint.

Definitions

Benefit

Field Type Description
benefit_id string Unique identifier for this benefit. This is the ID that will be returned in the entitlements API.

This ID is the Reward ID that has been created in the Reward Manager.
name string Name displayed to users on Twitch.
description string Description to be displayed to users on Twitch.
image_asset image Image to be displayed to the users on Twitch.

Entitlement

Field Type Description
id string Unique identifier of the entitlement.
benefit_id string Identifier of the benefit.
timestamp string UTC timestamp in ISO format when this entitlement was granted on Twitch.
user_id string Twitch User ID of the viewer who was granted the entitlement.
game_id string Twitch Game ID of the game being played when the benefit was entitled.
fulfillment_status string The fulfillment status of the entitlement as determined by the game developer. Valid values are "CLAIMED" or "FULFILLED".
updated_at string UTC timestamp in ISO format for when this entitlement was last updated.

Campaign Marketing Page

You have the option of providing more information about your Twitch Drops Campaign by linking to a custom website, which will be available for the Twitch community to learn more about the event you are hosting. Typically, this page includes more information about your event and how Twitch Drops will be a cornerstone of your marketing plan. For example, you may use Twitch Drops to drive viewers to watch your weekly developer diary stream on an upcoming game. The marketing page can tell viewers about the stream event, and can also inform them of the exclusive item you plan to give away.

Create a Reward

Before creating Drops Campaigns, you can use the Rewards Manager to set up the rewards you will associate with Drops that will be granted to Twitch viewers. Alternatively, you can add rewards while creating Drops within a campaign. When you create rewards via the Drops management interface, they will also be placed within the Rewards Manager.

To create a reward, select the Rewards Manager within the Drops product via your Organization’s Console. Then, click the create new reward button to fill out the details of the item you will award viewers who complete the Drops conditions (you’ll set these up later within a Drops Campaign).

Field Name Details and Usage Example
Reward Image This image will display within the notification call out when a Drop campaign is enabled, the streamer dashboard, and the inventory card UI when a viewer earns the reward. It must be a 160x160 px JPG or PNG, less than 1 MB in size. image of a shortsword
Reward Name The name of the reward. Ultimate Ball
Game The game this reward is associated with. Games in this list must be owned by the organization and must have a Twitch Client mapped to it within Drops Settings. Super Soccer 2023
Reward Connection URL The URL viewers will go to link their Twitch account with your game’s identity service. Viewers expect that this identity link will provide the access needed to have the reward delivered to them after earning it on Twitch. https://supersoccer2023.com/link
iOS Based Reward If this reward is associated with an item that can be used within an iOS app or game, this field must be toggled to ON.

This will hide the Drops campaign on iOS devices. However, viewers’ progress on iOS will still be tracked and they would be able to claim the reward on other platforms.		 OFF
Reward ID (optional) You can specify a unique ID for this reward in case your game’s fulfillment service expects a certain identifier for the item granted. If you do not specify an ID, we will generate a GUID upon saving the reward on Twitch. 398dnb-9kdlsnm-dasdfk2-doandbo3-onbm21

This ID will be surfaced as benefit_id in the API.

After providing these details, saving the reward will make it available to any Drops added to a Drops campaign.

Create a Drops Campaign

To run a Drop on Twitch, you will first need to set up a Drops Campaign, which allows you to schedule several Drops in advance of the event you’ll host for the Twitch community. Prior to launch, campaign information will be displayed for creators, so they can ensure their streaming schedules align with your event. You can run up to seven Drops during a campaign.

Log on to the Twitch Developer Console (using the dropdown menu at the top right) and switch to your Organization’s console where you will create the campaign. Under the Drops product, select Create Drop Campaign. Add the following information that will be displayed for creators before, during and after your campaign:

Field Name Details and Usage Example
Campaign Image This image will be displayed for both viewers and creators before, during and after your campaign. It should visually summarize the event that your Drops will occur when creators stream your game on Twitch. It should be a 160x160px PNG or JPG and less than 1MB. image of a file box
Campaign Name This brief description gives streamers and viewers an overview of the campaign event. It can be no longer than 25 characters. “Super Soccer 2023 Launch”
Start Date & Time, End Date & Time The duration of the campaign event. All Drops set up within the campaign must be within the time frame specified at the campaign level here. October 10th 2023 12:00PM (UTC) to November 10th 2023 12:00PM (UTC)

* Campaigns have a 28-day maximum duration.
Game The game category creators must stream in order for Drops to be present on their channel. When a creator goes live during the campaign timeframe, viewers who visit the channel will have the ability to earn the Drops set up within the campaign. Super Soccer 2023
Drops Connection URL The URL viewers must visit to link their Twitch account with your system which will fulfill the entitlements granted during the Drop Campaign.

*In cases where the account link connection cannot be done from a website, use this URL to link to detailed instructions on how to link the users Twitch and game accounts.		 https://supersoccer2023.com/link
Drops Detail URL You can set up a marketing page to provide viewers and streamers more information about the campaign event, the rewards that they could earn, and the conditions required to earn the rewards. https://supersoccer2023.com/twitchdropslaunch
Description This description is visible on the Drops page within the creator’s dashboard. It should cover all of the details of the campaign to entice creators to play your game during the campaign time period. Super Soccer 2023 is an arcade style soccer game that lets you play as the game’s legends at the world’s greatest stages… or at the public park. During October, we’ll be giving away exclusive balls that unlock certain capabilities within the game, exclusive to our fans on Twitch. See you on the field!

Once you create the campaign, you’ll be taken to the Campaign Details page where you can see a preview of how your campaign information and rewards will be presented to creators and viewers before, during and after the campaign.

Next, you will set up Drops that will be distributed to viewers during the campaign. You can add up to seven Drops, which will be distributed over a concurrent time frame during the campaign. There are two types of Drops requirements:

After adding the Drops to your campaign, you can test the campaign to ensure it is ready for your event, and then enable the campaign for creators when the campaign start time occurs.

Time-Based Drops

Time-Based Drops distribute rewards when viewers have watched a creator stream your game for a specified amount of time. Twitch monitors the amount of time viewers spend across all channels streaming your game, so all you have to do is fulfill the rewards they are entitled to.

Add a time-based Drop to an existing campaign

  1. Click on the Drops tab within a campaign and click the Create New Drop button.
  2. Specify a name for the Drop, and make sure Watch Time is selected for the Requirement Type.
  3. Set the Watch Time requirement duration using the dropdown menu (ranging in increments from 15 minutes to 15 hours).
  4. Click the Create Drop button.

After creating the Drop, all you have to do is add the items to distribute when the condition has been met, and then you are ready for testing.

If your campaign includes more than one Drop and you want viewers to earn each Drop at different lengths of time, simply configure the times accordingly. For example, if you have three drops within your campaign and want each to be earned 30 minutes after one another, set the first Drop for 30 minutes, the second Drop for 60 minutes, and the last Drop for 90 minutes. Viewers will progress on all drops at the same time but will only earn each Drops when completing the time-watch period specified.

Note: We recommend setting the watch time long enough for viewers to get a sense of the game, but not too much time that would demotivate them from earning your reward. Drops are limited to durations between a minimum of 15 minutes and a maximum of 4 hours.

Subscription-based Drops

Subscription-Based Drops distribute rewards when viewers have subscribed to or gifted subscriptions in a channel to meet your subscription count requirement. Twitch monitors the subscriptions across all channels streaming your game, so all you have to do is fulfill the rewards they are entitled to.

Add a subscription-based Drop to an existing campaign

  1. Click on the Drops tab within a campaign and click the Create New Drop button.
  2. Specify a name for the Drop, and make sure Gifts & Subs is selected for the Requirement Type.
  3. Set the Subscription Count requirement using the dropdown menu (ranging from 1 to 5).
  4. Click the Create Drop button.

Add Rewards

Rewards are the items you will distribute to viewers after they have completed a Drop’s watch time or subscription count requirements. You can add up to 3 rewards to a Drop, all of which will be rewarded upon completion of the rule. Rewards are first created in the Reward Manager and then added to a Drop by navigating to the Drops campaign tab and then clicking the + button for a specific Drop.

Rewards can be anything from in-game items (e.g. a limited edition ball), consumable items (e.g. coins or points) or access to a game (e.g. beta access via a direct entitlement). Most users of our Drops features distribute exclusive rewards you can only get on Twitch, distributing more rare items based on the difficulty of the rule specified.

Test the Drop

We strongly encourage testing any Drop before you activate it as part of a Drops Campaign. To make sure your event is kept a surprise to the community, you can use two access lists to limit the number of accounts who can preview the Drop before it goes live to all viewers and creators.

1. Specify Test Viewers and Creator Access

Click on the Access tab within a campaign and you will see two sections: Test Viewers and Creator Campaign Access. Test Viewers can participate in Drop campaigns when the campaign status is in the test state. To specify test viewer(s), input their username(s) within the Test Accounts.

Creator Campaign Access allows you to specify creators whose communities can participate in your drop campaign. To specify creator(s), make sure Available for allow list channels is checked and the creator(s) username is entered amongst the Allow List Channels. The allow list is only valid when the campaign status is in test or active state.

Using one of the accounts that will watch your test stream, test out your account linking flow.

3. Stream on a Twitch streamer account

Start streaming on Twitch, ensuring (1) the category is set to your game, (2) within your creator dashboard Drops are enabled, and (3) Drops are enabled for your Drops campaign.

4. Complete the Drop requirement with a test viewer

Complete either the watch time or subscription count requirement to earn the Drop.

5. Claim the Drop with a test viewer and creator channel

Test that the user is able to claim an entitlement on Twitch.

6. Verify the Entitlement was granted by Twitch

When a viewer claims a Drop, you can call the Entitlements API to get viewer entitlement data.

7. Award a test Entitlement to the Twitch viewer

Make sure you are able to process entitlements and track fulfillment for your test users.

8. Grant item in-game

Test that the user is able to claim an entitlement in-game.

Enabling a Drops Campaign

Once you have added the Drops to the campaign and tested them within your organization, you are ready to go live! Click Change Status to select the Enabled state. You will see a preview sheet of the campaign, which you can use as a last minute checklist for the details and drops you have set up for this campaign.

Once you set the status to enabled, you will see one of three states:

Status Visibility Campaign Edit Restrictions
Upcoming: The start time is in the future. Creators will be able to view campaign details in the creator dashboard. Campaign details can be changed.

The start date can be moved up to the present.
Live: The start time is in the past and the end time is in the future. Creators will be able to view the campaign details in the creator dashboard.

Viewers will see the game has Drops Enabled in the Twitch directory.

Channels streaming the game live will show the Drops Enabled tag.

Viewers following streamers that go live with your title that has a campaign enabled will receive a notification encouraging them to tune in.		 The campaign can no longer move to a disabled or testing state.

Only changes to metadata such as campaign/reward names, URLs, descriptions or the allowlist can be made in this state. Changes to Drops or Drop rules are not possible.
Expired: The end time is in the past. The campaign will be hidden from all views. Any rewards earned by viewers will remain within their inventory, if they have earned them or claimed them already. No changes can be made to any campaign or drop details.

If you need to terminate the campaign while it is Live, you may change the status to Expired Manually.

Running a Successful Drops Campaign

A Drops campaign is most effective in conjunction with additional marketing that drives interest to your campaign on Twitch. Throughout your game’s lifecycle, you can use Drops campaigns to attract new player interest in your title, or reward your most loyal fans. Here are a few tips to ensure your Drops campaign resonates with the Twitch community and excite your player base.

Create a Gaming Moment

Run a Drops campaign during a major moment for your game, such as its world premiere, beginning of open beta, or the release of a new trailer. With Twitch Drops, viewers can link their account to your identity system in advance of your game’s launch. You can seed viewer excitement with exclusive content that they will have available at Day 1 of launch.

Be Thoughtful with your Campaign and Reward Names

Clear naming of your campaign and campaign rewards make for a better experience for creators and viewers. Consider using nomenclature your community is familiar with so there is a clear understanding of what the campaign is, and what rewards can be earned. As an example, a campaign name of “The Cool Game Winter Challenge Event” where you can earn “500 Super Gems” clearly illustrates what campaign is running and what rewards viewers can earn.

Limit the Number of Campaigns You Create

We have seen that having many concurrent global Drops campaigns running at the same time does not create a good user experience on Twitch, and in fact, causes user confusion and dilutes your message. We have also seen increased Customer Service activity for game developers when there are multiple campaigns running, with users reaching out to ask about individual rewards that they did not receive. If you do want to run multiple campaigns at the same time, we recommend having at most 2 campaigns on a channel at a time, with one global campaign and one channel specific campaign.

Make Drops Rewarding

To make the biggest impact for your Drops Campaign, providing the rewards that excite your community is critical to achieving success. Creating exclusive rewards such as beta access or a unique skin that can only be achieved through Drops will drive your audience to participate and attract new potential fans.

Be the First to Give News and Updates

Many developers use Twitch to showcase the latest updates in their game as part of a regular diary stream. You can set up Twitch Drops to be available during these streams, driving viewership to your show while showing off your latest release.

Obligations

For more information regarding your obligations when running Drops campaigns, please see schedule 3 of the Developer Services Agreement.

FAQ

How long do I need to support a user claiming a Drop and linking their account after claiming for fulfillment?

In most circumstances, developers are required to fulfill viewer rewards that claim and link their accounts at least 14 days from the campaign ending. For certain time sensitive campaigns, such as a limited time beta, this requirement may be waived.

Will Twitch Drops increase the rank of my game in the Twitch directory?

In conjunction with a strategic marketing campaign, Twitch Drops are effective in enticing creators to play your title and motivate viewers to check out your game on Twitch. We recommend working with our creators in advance of the campaign to make sure they can show off the best of your game during the Drops Campaign. We also recommend using other social channels to inform viewers about the Drop in advance.

How do I view campaign analytics for my Drop Campaigns?

A downloadable analytics CSV file will be made available in the near future.

Where can I get support for Drops?

We recommend reading the Twitch Developer Playbook to see how Drops fits in as part of a broader set of strategies to grow your game’s engagement on Twitch.

To get additional support, see this page for all the resources available to you, including access to our developer forums and the TwitchDev Discord server.

How do I remove an account link?

Since account linking is maintained by you, you will need to remove links between a Twitch account and a game account. We also recommend that you also revoke the OAuth access token.

What type of rewards can I give out?

While we do not have specific recommendations on the types of rewards to give out, we do recommend that you avoid stackable/transferable Drops items, as this encourages farming behavior in which viewers create multiple accounts and watch different channels from multiple browser windows. For more information on your obligations when running Drops campaigns, please see refer to the Twitch Developer Services Agreement.

How do I handle account de-linking by users?

It is important to think about how to handle users disconnecting their Twitch account from your game account. To check if a user has disconnected their account, you can check the validity of their OAuth token.

Here are some recommendations to handle account relinking by users:

How do I handle banned/suspended Accounts?

If an account is banned or suspended, the OAuth token is invalidated. Please check the validity of a user’s (streamer or viewer) OAuth token before granting in-game items.

Can streamers opt-out of a Drops campaign when it applies to an entire category?

Yes. Streamers have the ability to globally enable or disable Drops on their channel using the toggle in the Viewer Rewards section of the Creator Dashboard. Streamers can also disable specific Drops campaigns from this section of the dashboard as well by expanding each open campaign.

Docs Status Support Showcase Blog