Entitlements - API Reference | Twitch Developers

Get Drops Entitlements

Gets an organization's list of entitlements that have been granted to a game, a user, or both.

The following table identifies the request parameters that you may specify based on the type of access token used.

Access token type	Parameter	Description
App	None	If you don't specify request parameters, the request returns all entitlements that your organization owns.
App	user_id	The request returns all entitlements for any game that the organization granted to the specified user.
App	user_id, game_id	The request returns all entitlements that the specified game granted to the specified user.
App	game_id	The request returns all entitlements that the specified game granted to all entitled users.
User	None	If you don't specify request parameters, the request returns all entitlements for any game that the organization granted to the user identified in the access token.
User	user_id	The ID must match the user identified in the access token. The request returns the same entitlements as specifying no parameters.
User	user_id, game_id	The user ID must match the user identified in the access token. The request returns the same entitlements as specifying only game_id.
User	game_id	The request returns all entitlements that the specified game granted to the user identified in the access token.

Except when you specify id, or both a user and a game (user_id and game_id, or game_id with a user access token), the response includes only entitlements granted in the last 6 months.

Note

Entitlements returned in the response body data are not guaranteed to be sorted by any field returned by the API. To retrieve CLAIMED or FULFILLED entitlements, use the 'fulfillment_status' query parameter to filter results. To retrieve entitlements for a specific game, use the 'game_id' query parameter to filter results.

Endpoint

GEThttps://api.twitch.tv/helix/entitlements/drops

Authorization

Requires one of the following:

A user access token.The Client ID associated with the access token must be owned by a user who is a member of the organization that holds ownership of the game.
An app access token.The Client ID associated with the access token must be owned by a user who is a member of the organization that holds ownership of the game.

Query Parameters

idString
An ID that identifies the entitlement to get. Include this parameter for each entitlement you want to get. For example, 'id=1234&id=5678'. You may specify a maximum of 100 IDs.

If you specify id, the user_id, game_id, and fulfillment_status filters don't apply.
user_idString
An ID that identifies a user that was granted entitlements.
game_idString
An ID that identifies a game that offered entitlements.
fulfillment_statusString
The entitlement's fulfillment status. Used to filter the list to only those with the specified status. The value is case-insensitive.
Possible values
- CLAIMED
- FULFILLED
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More
firstInteger
The maximum number of entitlements to return per page in the response. The minimum page size is 1 entitlement per page and the maximum is 1000. The default is 20.

Response Body

dataObject[]
The list of entitlements.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies the entitlement.
- data.benefit_idString
  An ID that identifies the benefit (reward).
- data.timestampString
  The UTC date and time (in RFC3339 format) of when the entitlement was granted.
- data.user_idString
  An ID that identifies the user who was granted the entitlement.
- data.game_idString
  An ID that identifies the game the user was playing when the reward was entitled.
- data.fulfillment_statusString
  The entitlement's fulfillment status.
  Possible values
  - CLAIMED
  - FULFILLED
- data.last_updatedString
  The UTC date and time (in RFC3339 format) of when the entitlement was last updated.
paginationObject
The information used to page through the list of results. The response doesn't include this object if there are no more pages left to page through, or if you specify id. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Set the request's after query parameter to this value to page forward through the results.

Response Codes

200OK: Successfully retrieved the entitlements.
400Bad Request: The value in the fulfillment_status query parameter is not valid.
The ID in the user_id query parameter must match the user ID in the user access token.
The client in the access token is not associated with a known organization.
The owner of the client in the access token is not a member of the organization.
The first query parameter is outside the allowed range of values.
The request exceeds the maximum number of id query parameters that you may specify.
The cursor specified in the after query parameter is not valid.
401Unauthorized: The ID in the Client-Id header must match the Client ID in the access token.
The Authorization header is required and must specify an app access token or user access token.
The access token is not valid.
403Forbidden: The organization associated with the client in the access token must own the game specified in the game_id query parameter.
The organization associated with the client in the access token must own the entitlements specified in the id query parameter.
500Internal Server Error: An internal server error occurred. Please report this issue on our issue tracker.

Request Example

curl -X GET 'https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/entitlements/drops",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "user_id": "25009227",
        "game_id": "33214",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/entitlements/drops?user_id=25009227&game_id=33214")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
      "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:17:53.325Z",
      "user_id": "25009227",
      "game_id": "33214",
      "fulfillment_status": "CLAIMED",
      "last_updated": "2019-01-28T04:17:53.325Z"
    },
    {
      "id": "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
      "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:16:53.325Z",
      "user_id": "25009227",
      "game_id": "33214",
      "fulfillment_status": "CLAIMED",
      "last_updated": "2021-06-15T04:16:53.325Z"
    },
    {
      "id": "d8879baa-3966-4d10-8856-15fdd62cce02",
      "benefit_id": "cdfdc5c3-65a2-43bc-8767-fde06eb4ab2c",
      "timestamp": "2019-01-28T04:15:53.325Z",
      "user_id": "25009227",
      "game_id": "33214",
      "fulfillment_status": "FULFILLED",
      "last_updated": "2019-01-28T04:17:53.325Z"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudW..."
  }
}

Update Drops Entitlements

Updates the Drop entitlement's fulfillment status.

The following table identifies which entitlements are updated based on the type of access token used.

Access token type	Data that's updated
App	Updates all entitlements with benefits owned by the organization in the access token.
User	Updates all entitlements owned by the user in the access token and where the benefits are owned by the organization in the access token.