Contents

Code Redemption API

Introduction

Codes are redeemable alphanumeric strings tied only to the bits product. This third-party API allows other parties to redeem codes on behalf of users. Third-party app and extension developers can use the API to provide rewards of bits from within their games.

We provide sets of codes to the third party as part of a contract agreement. The third-party program then calls this API to credit the Twitch user by submitting specific code(s). This means that a bits reward can be directly applied without the user having to follow any manual steps (e.g., visiting the Twitch redemption page).

All codes are single-use. Once a code has been redeemed, via either this API or the site page, then the code is no longer valid for any further use.

Definitions

Term Description
Code A fifteen character (plus optional hyphen separators) alphanumeric string.
e.g. ABCDE-12345-FGHIJ
Redeem Apply the product associated with a given code to a Twitch user account.

Scope

This section defines what is in and out of scope.

In Scope:

Out of Scope:

Specification

This section describes the Helix API design specification.

API Overview

ID PRD ID Method Endpoint
API001 TBD2 GET /helix/entitlements/codes
API002 TBD2 POST /helix/entitlements/codes

API Detail

API001: Get Code Status API

GET /helix/entitlements/codes

Description

Gets the status of one or more provided codes. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user.

Authentication

Access is controlled via an app access token on the calling service. The client ID associated with the app access token must be approved by Twitch as part of a contracted arrangement.

Authorization

Callers with an app access token are authorized to redeem codes on behalf of any Twitch user account.

Query Parameters

Param Type Description
code String The code to get the status of. Repeat this query parameter additional times to get the status of multiple codes.
Ex: ?code=code1&code=code2
1-20 code parameters are allowed.
user_id Integer Represents a numeric Twitch user ID.
The user account which is going to receive the entitlement associated with the code.

Return Values

Param Type Description
results Array of payloads each of which includes code (string) and status (string). Indicates the current status of each key when checking key status. 

Indicates the success or error state of each key when redeeming. See “Code Statuses” section.

Sample Request

GET /helix/entitlements/codes?code=11111-11111-11111&code=22222-22222-22222

Sample Response

{
  results : [
    {
      "code" : "11111-11111-11111",
      "status" : "UNUSED"
    },
    {
      "code" : "22222-22222-22222",
      "status" : "ALREADY_CLAIMED"
    }
  ]
}

API002: Redeem Code API

POST /helix/entitlements/codes

Description

Redeem one or more provided codes to the authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user.

Authentication

Access is controlled via an app access token on the calling service. The client ID associated with the app access token must be one approved by Twitch.

Authorization

Callers with an app access token as described above are authorized to redeem codes on behalf of any Twitch user account.

Query Params

Param Type Description
code String The code to redeem to the authenticated user’s account. Repeat this query parameter additional times to redeem multiple codes.
Ex: ?code=code1&code=code2
1-20 code parameters are allowed.
user_id Integer Represents a numeric Twitch user ID.
The user account which is going to receive the entitlement associated with the code.

Return Values

Param Type Description
results Array of payloads each of which includes code (string) and status (string). Indicates the success or error state of each key when redeeming. See “Code Statuses” section.

Sample Request

POST /helix/entitlements/codes?code=11111-11111-11111&code=22222-22222-22222
{}

Sample Response

{
  results : [
    {
      "code" : "11111-11111-11111",
      "status" : "SUCCESSFULLY_REDEEMED"
    },
    {
      "code" : "22222-22222-22222",
      "status" : "ALREADY_CLAIMED"
    }
  ]
}

Code Statuses

Code Description
SUCCESSFULLY_REDEEMED Request successfully redeemed this code to the authenticated user’s account.

This status will only ever be encountered when calling the POST API to redeem a key.
ALREADY_CLAIMED Code has already been claimed by a Twitch user.
EXPIRED Code has expired and can no longer be claimed.
USER_NOT_ELIGIBLE User is not eligible to redeem this code.
NOT_FOUND Code is not valid and/or does not exist in our database.
INACTIVE Code is not currently active.
UNUSED Code has not been claimed.

This status will only ever be encountered when calling the GET API to get a keys status.
INCORRECT_FORMAT Code was not properly formatted.
INTERNAL_ERROR Indicates some internal and/or unknown failure handling this code.

HTTP Response Codes

API calls may result in these standard response codes for the following specific reasons:

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limit

500 Internal Server Error

503 Service Unavailable