Charity - API Reference | Twitch Developers

Get Charity Campaign

Gets information about the charity campaign that a broadcaster is running. For example, the campaign's fundraising goal and the current amount of donations.

To receive events when progress is made towards the campaign's goal or the broadcaster changes the fundraising goal, subscribe to the channel.charity_campaign.progress subscription type.

Endpoint

GEThttps://api.twitch.tv/helix/charity/campaigns

Authorization

Requires one of the following:

A user access token that includes the channel:read:charity scope.

Query Parameters

broadcaster_idStringRequired
The ID of the broadcaster that's currently running a charity campaign. This ID must match the user ID in the access token.

Response Body

dataObject[]
A list that contains the charity campaign that the broadcaster is currently running. The list is empty if the broadcaster is not running a charity campaign; the campaign information is not available after the campaign ends.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies the charity campaign.
- data.broadcaster_idString
  An ID that identifies the broadcaster that's running the campaign.
- data.broadcaster_loginString
  The broadcaster's login name.
- data.broadcaster_nameString
  The broadcaster's display name.
- data.charity_nameString
  The charity's name.
- data.charity_descriptionString
  A description of the charity.
- data.charity_logoString
  A URL to an image of the charity's logo. The image's type is PNG and its size is 100px X 100px.
- data.charity_websiteString
  A URL to the charity's website.
- data.current_amountObject
  The current amount of donations that the campaign has received.
  Hide child attributesShow child attributes
  - data.current_amount.valueInteger
    The monetary amount. The amount is specified in the currency's minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, 'value' is set to 550.
  - data.current_amount.decimal_placesInteger
    The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate 'value' from minor units to major units by using the formula:
    
    'value / 10^decimal_places'
  - data.current_amount.currencyString
    The ISO-4217 three-letter currency code that identifies the type of currency in 'value'.
- data.target_amountObject
  The campaign's fundraising goal. If the broadcaster has not defined a fundraising goal, value is 0.
  Hide child attributesShow child attributes
  - data.target_amount.valueInteger
    The monetary amount. The amount is specified in the currency's minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, 'value' is set to 550.
  - data.target_amount.decimal_placesInteger
    The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate 'value' from minor units to major units by using the formula:
    
    'value / 10^decimal_places'
  - data.target_amount.currencyString
    The ISO-4217 three-letter currency code that identifies the type of currency in 'value'.

Response Codes

200OK: Successfully retrieved information about the broadcaster's active charity campaign.
400Bad Request: The broadcaster_id query parameter is required.
401Unauthorized: The ID in the broadcaster_id query parameter must match the user ID in the access token.
The Authorization header is required and must contain a user access token.
The user access token must include the channel:read:charity scope.
The access token is not valid.
The client ID specified in the Client-Id header must match the client ID specified in the access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456' \
  -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/charity/campaigns?broadcaster_id=123456" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456", {
  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/charity/campaigns",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "broadcaster_id": "123456",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456", 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/charity/campaigns?broadcaster_id=123456");

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/charity/campaigns?broadcaster_id=123456");
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/charity/campaigns?broadcaster_id=123456")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

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

Response Example

{
  "data": [
    {
      "id": "123-abc-456-def",
      "broadcaster_id": "123456",
      "broadcaster_name": "SunnySideUp",
      "broadcaster_login": "sunnysideup",
      "charity_name": "Example name",
      "charity_description": "Example description",
      "charity_logo": "https://abc.cloudfront.net/ppgf/1000/100.png",
      "charity_website": "https://www.example.com",
      "current_amount": {
        "value": 86000,
        "decimal_places": 2,
        "currency": "USD"
      },
      "target_amount": {
        "value": 1500000,
        "decimal_places": 2,
        "currency": "USD"
      }
    }
  ]
}

Get Charity Campaign Donations

Gets the list of donations that users have made to the broadcaster's active charity campaign.

To receive events as donations occur, subscribe to the channel.charity_campaign.donate subscription type.