Channel Points

Get Custom Reward

Endpoint

GEThttps://api.twitch.tv/helix/channel_points/custom_rewards

Authorization

Requires one of the following:

• A user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.

Query Parameters

• broadcaster_idStringRequired
  The ID of the broadcaster whose custom rewards you want to get. This ID must match the user ID found in the OAuth token.
• idString

  A list of IDs to filter the rewards by. To specify more than one ID, include this parameter for each reward you want to get. For example, 'id=1234&id=5678'. You may specify a maximum of 50 IDs.

  Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found.

• only_manageable_rewardsBoolean
  A Boolean value that determines whether the response contains only the custom rewards that the app may manage (the app is identified by the ID in the Client-Id header). Set to true to get only the custom rewards that the app may manage. The default is false.

Response Body

• dataObject[]
  A list of custom rewards. The list is in ascending order by 'id'. If the broadcaster hasn't created custom rewards, the list is empty.
  Hide child attributesShow child attributes

  • data.broadcaster_idString
    The ID that uniquely identifies the broadcaster.
  • data.broadcaster_loginString
    The broadcaster's login name.
  • data.broadcaster_nameString
    The broadcaster's display name.
  • data.idString
    The ID that uniquely identifies this custom reward.
  • data.titleString
    The title of the reward.
  • data.promptString
    The prompt shown to the viewer when they redeem the reward if user input is required (see the 'is_user_input_required' field).
  • data.costInteger
    The cost of the reward in Channel Points.
  • data.imageObject
    A set of custom images for the reward. This field is null if the broadcaster didn't upload images.
    Hide child attributesShow child attributes

    • data.image.url_1xString
      The URL to a small version of the image.
    • data.image.url_2xString
      The URL to a medium version of the image.
    • data.image.url_4xString
      The URL to a large version of the image.
  • data.default_imageObject
    A set of default images for the reward.
    Hide child attributesShow child attributes

    • data.default_image.url_1xString
      The URL to a small version of the image.
    • data.default_image.url_2xString
      The URL to a medium version of the image.
    • data.default_image.url_4xString
      The URL to a large version of the image.
  • data.background_colorString
    The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
  • data.is_enabledBoolean
    A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren't shown to the user.
  • data.is_user_input_requiredBoolean
    A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the user is prompted.
  • data.max_per_stream_settingObject
    The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.
    Hide child attributesShow child attributes

    • data.max_per_stream_setting.is_enabledBoolean
      A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
    • data.max_per_stream_setting.max_per_streamInt64
      The maximum number of redemptions allowed per live stream.
  • data.max_per_user_per_stream_settingObject
    The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
    Hide child attributesShow child attributes

    • data.max_per_user_per_stream_setting.is_enabledBoolean
      A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
    • data.max_per_user_per_stream_setting.max_per_user_per_streamInt64
      The maximum number of redemptions allowed per user per live stream.
  • data.global_cooldown_settingObject
    The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
    Hide child attributesShow child attributes

    • data.global_cooldown_setting.is_enabledBoolean
      A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
    • data.global_cooldown_setting.global_cooldown_secondsInt64
      The cooldown period, in seconds.
  • data.is_pausedBoolean
    A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can't redeem paused rewards.
  • data.is_in_stockBoolean
    A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can't redeem out of stock rewards.
  • data.should_redemptions_skip_request_queueBoolean
    A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.
  • data.redemptions_redeemed_current_streamInteger
    The number of redemptions redeemed during the current live stream. The number counts against the 'max_per_stream_setting' limit. This field is null if the broadcaster's stream isn't live or max_per_stream_setting isn't enabled.
  • data.cooldown_expires_atString
    The timestamp of when the cooldown period expires. Is null if the reward isn't in a cooldown state. See the 'global_cooldown_setting' field.

Response Codes

200OK

Successfully retrieved the broadcaster's list of custom rewards.

400Bad Request

• The broadcaster_id query parameter is required.
• The request exceeds the maximum number of id query parameters that you may specify.

401Unauthorized

• The Authorization header must specify a user access token.
• The user access token must include the channel:read:redemptions or channel:manage:redemptions scope.
• The ID in broadcaster_id must match the user ID in the user access token.
• The OAuth token is not valid.
• The ID in the Client-Id header must match the Client ID in the OAuth token.

403Forbidden

• The broadcaster is not a partner or affiliate.

404Not Found

• All of the custom rewards specified using the id query parameter were not found.

500Internal Server Error

An internal server error occurred. Please report this issue on our issue tracker.

Create Custom Rewards

Endpoint

POSThttps://api.twitch.tv/helix/channel_points/custom_rewards

Authorization

Requires one of the following:

• A user access token that includes the channel:manage:redemptions scope.

Query Parameters

• broadcaster_idStringRequired
  The ID of the broadcaster to add the custom reward to. This ID must match the user ID found in the OAuth token.

Request Body

• titleStringRequired
  The custom reward's title. The title may contain a maximum of 45 characters and it must be unique (case-insensitive) amongst all of the broadcaster's custom rewards.
• costInt64Required
  The cost of the reward, in Channel Points. The minimum is 1 point and the maximum is 1,000,000,000 points.
• promptString
  The prompt shown to the viewer when they redeem the reward. Specify a prompt if 'is_user_input_required' is true.
• is_enabledBoolean
  A Boolean value that determines whether the reward is enabled. Viewers see only enabled rewards. The default is true.
• background_colorString
  The background color to use for the reward. Specify the color using Hex format (for example, #9147FF). If you omit it or set it to an empty string, the reward gets a randomly chosen color.
• is_user_input_requiredBoolean
  A Boolean value that determines whether the user needs to enter information when redeeming the reward. See the 'prompt' field. The default is false.
• is_max_per_stream_enabledBoolean
  A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the 'max_per_stream' field). The default is false.
• max_per_streamInteger
  The maximum number of redemptions allowed per live stream. Applied only if 'is_max_per_stream_enabled' is true. The minimum value is 1.
• is_max_per_user_per_stream_enabledBoolean
  A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see the 'max_per_user_per_stream' field). The default is false.
• max_per_user_per_streamInteger
  The maximum number of redemptions allowed per user per stream. Applied only if 'is_max_per_user_per_stream_enabled' is true. The minimum value is 1.
• is_global_cooldown_enabledBoolean
  A Boolean value that determines whether to apply a cooldown period between redemptions (see the 'global_cooldown_seconds' field for the duration of the cooldown period). The default is false.
• global_cooldown_secondsInteger
  The cooldown period, in seconds. Applied only if the 'is_global_cooldown_enabled' field is true. The minimum value is 1; however, the minimum value is 60 for it to be shown in the Twitch UX.
• should_redemptions_skip_request_queueBoolean
  A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. The default is false.

Response Body

• dataObject[]
  A list that contains the single custom reward you created.
  Hide child attributesShow child attributes

  • data.broadcaster_idString
    The ID that uniquely identifies the broadcaster.
  • data.broadcaster_loginString
    The broadcaster's login name.
  • data.broadcaster_nameString
    The broadcaster's display name.
  • data.idString
    The ID that uniquely identifies this custom reward.
  • data.titleString
    The title of the reward.
  • data.promptString
    The prompt shown to the viewer when they redeem the reward if user input is required (see the 'is_user_input_required' field).
  • data.costInteger
    The cost of the reward in Channel Points.
  • data.imageObject
    A set of custom images for the reward. This field is set to null if the broadcaster didn't upload images.
    Hide child attributesShow child attributes

    • data.image.url_1xString
      The URL to a small version of the image.
    • data.image.url_2xString
      The URL to a medium version of the image.
    • data.image.url_4xString
      The URL to a large version of the image.
  • data.default_imageObject
    A set of default images for the reward.
    Hide child attributesShow child attributes

    • data.default_image.url_1xString
      The URL to a small version of the image.
    • data.default_image.url_2xString
      The URL to a medium version of the image.
    • data.default_image.url_4xString
      The URL to a large version of the image.
  • data.background_colorString
    The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
  • data.is_enabledBoolean
    A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren't shown to the user.
  • data.is_user_input_requiredBoolean
    A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the reward requires user input.
  • data.max_per_stream_settingObject
    The settings used to determine whether to apply a maximum to the number to the redemptions allowed per live stream.
    Hide child attributesShow child attributes

    • data.max_per_stream_setting.is_enabledBoolean
      A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
    • data.max_per_stream_setting.max_per_streamInt64
      The maximum number of redemptions allowed per live stream.
  • data.max_per_user_per_stream_settingObject
    The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
    Hide child attributesShow child attributes

    • data.max_per_user_per_stream_setting.is_enabledBoolean
      A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
    • data.max_per_user_per_stream_setting.max_per_user_per_streamInt64
      The maximum number of redemptions allowed per user per live stream.
  • data.global_cooldown_settingObject
    The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
    Hide child attributesShow child attributes

    • data.global_cooldown_setting.is_enabledBoolean
      A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
    • data.global_cooldown_setting.global_cooldown_secondsInt64
      The cooldown period, in seconds.
  • data.is_pausedBoolean
    A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can't redeem paused rewards.
  • data.is_in_stockBoolean
    A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can't redeem out of stock rewards.
  • data.should_redemptions_skip_request_queueBoolean
    A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is UNFULFILLED and follows the normal request queue process.
  • data.redemptions_redeemed_current_streamInteger
    The number of redemptions redeemed during the current live stream. The number counts against the 'max_per_stream_setting' limit. This field is null if the broadcaster's stream isn't live or max_per_stream_setting isn't enabled.
  • data.cooldown_expires_atString
    The timestamp of when the cooldown period expires. Is null if the reward isn't in a cooldown state (see the 'global_cooldown_setting' field).

Response Codes

200OK

Successfully created the custom reward.

400Bad Request

• The request exceeds the maximum number of rewards allowed per channel.
• The broadcaster_id query parameter is required.
• The 'title' field is required.
• The 'title' must contain a minimum of 1 character and a maximum of 45 characters.
• The 'title' must be unique (case-insensitive) amongst all of the broadcaster's custom rewards.
• The 'cost' field is required.
• The 'cost' field must contain a minimum of 1 point and a maximum of 1,000,000,000 points.
• The 'background_color' must be in Hex format (for example, #9147FF).
• AutoMod rejected the content in the 'title' or 'prompt' field.
• If 'is_max_per_stream_enabled' is true, the minimum value for 'max_per_stream' is 1.
• If 'is_max_per_user_per_stream_enabled' is true, the minimum value for 'max_per_user_per_stream' is 1.
• If 'is_global_cooldown_enabled' is true, the minimum value for 'global_cooldown_seconds' is 1.

401Unauthorized

• The Authorization header is required and must specify a user access token.
• The user access token is missing the channel:manage:redemptions scope.
• The ID in broadcaster_id must match the user ID in the user access token.
• The OAuth token is not valid.
• The ID in the Client-Id header must match the Client ID in the OAuth token.

403Forbidden

• The broadcaster is not a partner or affiliate.

500Internal Server Error

An internal server error occurred. Please report this issue on our issue tracker.

Update Custom Reward

Endpoint

PATCHhttps://api.twitch.tv/helix/channel_points/custom_rewards

Authorization

Requires one of the following:

• A user access token that includes the channel:manage:redemptions scope.

Query Parameters

• broadcaster_idStringRequired
  The ID of the broadcaster that's updating the reward. This ID must match the user ID found in the OAuth token.
• idStringRequired
  The ID of the reward to update.

Request Body

• titleString
  The reward's title. The title may contain a maximum of 45 characters and it must be unique (case-insensitive) amongst all of the broadcaster's custom rewards.
• promptString
  The prompt shown to the viewer when they redeem the reward. Specify a prompt if 'is_user_input_required' is true. If the prompt is empty or contains only whitespace, the reward's current prompt isn't changed.
• costInt64
  The cost of the reward, in channel points. The minimum is 1 point and the maximum is 1,000,000,000 points.
• background_colorString
  The background color to use for the reward. Specify the color using Hex format (for example, \#00E5CB).
• is_enabledBoolean
  A Boolean value that indicates whether the reward is enabled. Set to true to enable the reward. Viewers see only enabled rewards.
• is_user_input_requiredBoolean
  A Boolean value that determines whether users must enter information to redeem the reward. Set to true if user input is required. See the 'prompt' field.
• is_max_per_stream_enabledBoolean
  A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the 'max_per_stream' field). Set to true to limit redemptions.
• max_per_streamInt64
  The maximum number of redemptions allowed per live stream. Applied only if 'is_max_per_stream_enabled' is true. The minimum value is 1.
• is_max_per_user_per_stream_enabledBoolean
  A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see 'max_per_user_per_stream'). Set to true to limit redemptions.
• max_per_user_per_streamInt64
  The maximum number of redemptions allowed per user per stream. Applied only if 'is_max_per_user_per_stream_enabled' is true. The minimum value is 1.
• is_global_cooldown_enabledBoolean
  A Boolean value that determines whether to apply a cooldown period between redemptions. Set to true to apply a cooldown period. For the duration of the cooldown period, see 'global_cooldown_seconds'.
• global_cooldown_secondsInt64
  The cooldown period, in seconds. Applied only if 'is_global_cooldown_enabled' is true. The minimum value is 1; however, for it to be shown in the Twitch UX, the minimum value is 60.
• is_pausedBoolean
  A Boolean value that determines whether to pause the reward. Set to true to pause the reward. Viewers can't redeem paused rewards..
• should_redemptions_skip_request_queueBoolean
  A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.

Response Body

• dataObject[]
  The list contains the single reward that you updated.
  Hide child attributesShow child attributes

  • data.broadcaster_idString
    The ID that uniquely identifies the broadcaster.
  • data.broadcaster_loginString
    The broadcaster's login name.
  • data.broadcaster_nameString
    The broadcaster's display name.
  • data.idString
    The ID that uniquely identifies this custom reward.
  • data.titleString
    The title of the reward.
  • data.promptString
    The prompt shown to the viewer when they redeem the reward if user input is required. See the 'is_user_input_required' field.
  • data.costInt64
    The cost of the reward in Channel Points.
  • data.imageObject
    A set of custom images for the reward. This field is null if the broadcaster didn't upload images.
    Hide child attributesShow child attributes

    • data.image.url_1xString
      The URL to a small version of the image.
    • data.image.url_2xString
      The URL to a medium version of the image.
    • data.image.url_4xString
      The URL to a large version of the image.
  • data.default_imageObject
    A set of default images for the reward.
    Hide child attributesShow child attributes

    • data.default_image.url_1xString
      The URL to a small version of the image.
    • data.default_image.url_2xString
      The URL to a medium version of the image.
    • data.default_image.url_4xString
      The URL to a large version of the image.
  • data.background_colorString
    The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
  • data.is_enabledBoolean
    A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren't shown to the user.
  • data.is_user_input_requiredBoolean
    A Boolean value that determines whether the user must enter information when they redeem the reward. Is true if the user is prompted.
  • data.max_per_stream_settingObject
    The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.
    Hide child attributesShow child attributes

    • data.max_per_stream_setting.is_enabledBoolean
      A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
    • data.max_per_stream_setting.max_per_streamInt64
      The maximum number of redemptions allowed per live stream.
  • data.max_per_user_per_stream_settingObject
    The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
    Hide child attributesShow child attributes

    • data.max_per_user_per_stream_setting.is_enabledBoolean
      A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
    • data.max_per_user_per_stream_setting.max_per_user_per_streamInt64
      The maximum number of redemptions allowed per user per live stream.
  • data.global_cooldown_settingObject
    The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
    Hide child attributesShow child attributes

    • data.global_cooldown_setting.is_enabledBoolean
      A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
    • data.global_cooldown_setting.global_cooldown_secondsInt64
      The cooldown period, in seconds.
  • data.is_pausedBoolean
    A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can't redeem paused rewards.
  • data.is_in_stockBoolean
    A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can't redeem out of stock rewards.
  • data.should_redemptions_skip_request_queueBoolean
    A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.
  • data.redemptions_redeemed_current_streamInteger
    The number of redemptions redeemed during the current live stream. The number counts against the 'max_per_stream_setting' limit. This field is null if the broadcaster's stream isn't live or max_per_stream_setting isn't enabled.
  • data.cooldown_expires_atString
    The timestamp of when the cooldown period expires. Is null if the reward isn't in a cooldown state. See the 'global_cooldown_setting' field.

Response Codes

200OK

Successfully updated the custom reward.

400Bad Request

• The broadcaster_id query parameter is required.
• The id query parameter is required.
• The 'title' must contain a minimum of 1 character and a maximum of 45 characters.
• The 'title' must be unique (case-insensitive) amongst all of the broadcaster's custom rewards.
• The 'cost' field must contain a minimum of 1 point and a maximum of 1,000,000,000 points.
• The 'background_color' must be in Hex format (for example, #00E5CB).
• AutoMod rejected the content in the 'title' or 'prompt' field.
• If 'is_max_per_stream_enabled' is true, the minimum value for 'max_per_stream' is 1.
• If 'is_max_per_user_per_stream_enabled' is true, the minimum value for 'max_per_user_per_stream' is 1.
• If 'is_global_cooldown_enabled' is true, the minimum value for 'global_cooldown_seconds' is 1.
• The 'max_per_stream' field is required if 'is_max_per_stream_enabled' is true.
• The 'max_per_user_per_stream' field is required if 'is_max_per_user_per_stream_enabled' is true.
• The 'global_cooldown_seconds' field is required if 'is_global_cooldown_enabled' is true.

401Unauthorized

• The Authorization header is required and must specify a user access token.
• The user access token must include the channel:manage:redemptions scope.
• The ID in broadcaster_id must match the user ID in the user access token.
• The OAuth token is not valide.
• The ID in the Client-Id header must match the Client ID in the OAuth token.

403Forbidden

• The ID in the Client-Id header must match the client ID used to create the custom reward.
• The broadcaster is not a partner or affiliate.

404Not Found

• The custom reward specified in the id query parameter was not found.

500Internal Server Error

An internal server error occurred. Please report this issue on our issue tracker.

Delete Custom Reward

Endpoint

DELETEhttps://api.twitch.tv/helix/channel_points/custom_rewards

Authorization

Requires one of the following:

• A user access token that includes the channel:manage:redemptions scope.

Query Parameters

• broadcaster_idStringRequired
  The ID of the broadcaster that created the custom reward. This ID must match the user ID found in the OAuth token.
• idStringRequired
  The ID of the custom reward to delete.

Response Codes

204No Content

Successfully deleted the custom reward.

400Bad Request

• The broadcaster_id query parameter is required.
• The id query parameter is required.

401Unauthorized

• The Authorization header is required and must specify a user access token.
• The user access token must include the channel:manage:redemptions scope.
• The ID in broadcaster_id must match the user ID in the user access token.
• The OAuth token is not valid.
• The ID in the Client-Id header must match the Client ID in the OAuth token.

403Forbidden

• The ID in the Client-Id header must match the client ID used to create the custom reward.
• The broadcaster is not a partner or affiliate.

404Not Found

• The custom reward specified in the id query parameter was not found.

500Internal Server Error

An internal server error occurred. Please report this issue on our issue tracker.

Get Custom Reward Redemption

Endpoint

GEThttps://api.twitch.tv/helix/channel_points/custom_rewards/redemptions

Authorization

Requires one of the following:

• A user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.

Query Parameters

• broadcaster_idStringRequired
  The ID of the broadcaster that owns the custom reward. This ID must match the user ID found in the user OAuth token.
• reward_idStringRequired
  The ID that identifies the custom reward whose redemptions you want to get.
• statusString
  The status of the redemptions to return. The possible values are case-sensitive. This parameter is required if you don't specify the id query parameter; if you specify id, it's ignored.

  Possible values

  • CANCELED
  • FULFILLED
  • UNFULFILLED
• idString

  A list of IDs to filter the redemptions by. To specify more than one ID, include this parameter for each redemption you want to get. For example, 'id=1234&id=5678'. You may specify a maximum of 50 IDs.

  Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found.

  If you specify id, the status, sort, first, and after query parameters don't apply: the response contains the redemptions regardless of their status, and it doesn't include the pagination object.

• sortString
  The order to sort redemptions by. The possible values are case-sensitive. The default is OLDEST.

  Possible values

  • OLDEST
  • NEWEST
• 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 redemptions to return per page in the response. The minimum page size is 1 redemption per page and the maximum is 50. The default is 20.

Response Body

• dataObject[]
  The list of redemptions for the specified reward. The list is empty if there are no redemptions that match the redemption criteria.
  Hide child attributesShow child attributes

  • data.broadcaster_idString
    The ID that uniquely identifies the broadcaster.
  • data.broadcaster_loginString
    The broadcaster's login name.
  • data.broadcaster_nameString
    The broadcaster's display name.
  • data.idString
    The ID that uniquely identifies this redemption.
  • data.user_loginString
    The user's login name.
  • data.user_idString
    The ID that uniquely identifies the user that redeemed the reward.
  • data.user_nameString
    The user's display name.
  • data.user_inputString
    The text the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required.
  • data.statusString
    The state of the redemption.

    Possible values

    • CANCELED
    • FULFILLED
    • UNFULFILLED
  • data.redeemed_atString
    The date and time of when the reward was redeemed, in RFC3339 format.
  • data.rewardObject
    The reward that the user redeemed.
    Hide child attributesShow child attributes

    • data.reward.idString
      The ID that uniquely identifies the redeemed reward.
    • data.reward.titleString
      The reward's title.
    • data.reward.promptString
      The prompt displayed to the viewer if user input is required.
    • data.reward.costInt64
      The reward's cost, in Channel Points.
• paginationObject
  Contains the information used to page through the list of results. The object contains a cursor whenever the page contains redemptions, even if it's the last page; it's empty if the page contains no redemptions. The response doesn't include this object if you specify the id query parameter. Read More.
  Hide child attributesShow child attributes

  • pagination.cursorString
    The cursor used to get the next page of results. Use the cursor to set the request's after query parameter.

Response Codes

200Ok

Successfully retrieved the list of redeemed custom rewards.

400Bad Request

• The broadcaster_id query parameter is required.
• The reward_id query parameter is required.
• The status query parameter is required if you didn't specify the id query parameter.
• The value in the status query parameter is not valid.
• The value in the sort query parameter is not valid.
• The value in the first query parameter is greater than 50.
• 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 Authorization header is required and must specify a user access token.
• The user access token must include the channel:read:redemptions or channel:manage:redemptions scope.
• The ID in broadcaster_id must match the user ID in the user access token.
• The OAuth token is not valid.
• The ID in the Client-Id header must match the Client ID in the OAuth token.

403Forbidden

• The ID in the Client-Id header must match the client ID used to create the custom reward.
• The broadcaster is not a partner or affiliate.

404Not Found

• The custom reward specified in the reward_id query parameter was not found.
• All of the redemptions specified using the id query parameter were not found.

500Internal Server Error

Update Redemption Status

Endpoint

PATCHhttps://api.twitch.tv/helix/channel_points/custom_rewards/redemptions

Authorization

Requires one of the following:

• A user access token that includes the channel:manage:redemptions scope.

Query Parameters

• idStringRequired
  A list of IDs that identify the redemptions to update. To specify more than one ID, include this parameter for each redemption you want to update. For example, 'id=1234&id=5678'. You may specify a maximum of 50 IDs.
• broadcaster_idStringRequired
  The ID of the broadcaster that's updating the redemption. This ID must match the user ID in the user access token.
• reward_idStringRequired
  The ID that identifies the reward that's been redeemed.

Request Body

• statusStringRequired
  The status to set the redemption to.

  Possible values

  • CANCELED
  • FULFILLED

Response Body

• dataObject[]
  The list of redemptions that you updated. The list doesn't include redemptions that weren't found, weren't UNFULFILLED, or belong to a different reward.
  Hide child attributesShow child attributes

  • data.broadcaster_idString
    The ID that uniquely identifies the broadcaster.
  • data.broadcaster_loginString
    The broadcaster's login name.
  • data.broadcaster_nameString
    The broadcaster's display name.
  • data.idString
    The ID that uniquely identifies this redemption..
  • data.user_idString
    The ID of the user that redeemed the reward.
  • data.user_nameString
    The user's display name.
  • data.user_loginString
    The user's login name.
  • data.rewardObject
    An object that describes the reward that the user redeemed.
    Hide child attributesShow child attributes

    • data.reward.idString
      The ID that uniquely identifies the reward.
    • data.reward.titleString
      The reward's title.
    • data.reward.promptString
      The prompt displayed to the viewer if user input is required.
    • data.reward.costInt64
      The reward's cost, in Channel Points.
  • data.user_inputString
    The text that the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required.
  • data.statusString
    The state of the redemption.

    Possible values

    • CANCELED
    • FULFILLED
    • UNFULFILLED
  • data.redeemed_atString
    The date and time of when the reward was redeemed, in RFC3339 format.

Response Codes

200OK

Successfully updated the redemption's status.

400Bad Request

• The broadcaster_id query parameter is required.
• The reward_id query parameter is required.
• The id query parameter is required and must contain at least one non-empty value.
• The 'status' field is required and must be CANCELED or FULFILLED.

401Unauthorized

• The Authorization header is required and must specify a user access token.
• The user access token must include the channel:manage:redemptions scope.
• The ID in broadcaster_id must match the user ID in the user access token.
• The OAuth token is not valid.
• The ID in the Client-Id header must match the Client ID in the OAuth token.

403Forbidden

• The ID in the Client-Id header must match the client ID used to create the custom reward.
• The broadcaster is not a partner or affiliate.

404Not Found

• The custom reward specified in the reward_id query parameter was not found.
• None of the redemptions specified using the id query parameter were found among the reward's UNFULFILLED redemptions.

500Internal Server Error

An internal server error occurred. Please report this issue on our issue tracker.