Introduction

The DonationAlerts public API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

HTTP API Requests

Requests and Responses

DonationAlerts public API endpoint for all HTTP methods is https://www.donationalerts.com/api/v1, unless specified otherwise.

All responses from our API are provided in JSON format, and in some cases, a 204 No Content response code with an empty response body may be returned.

Request example:

curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations \
    -H "Authorization: Bearer <token>"

Response example:

HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Sat, 1 Sep 2019 18:42:33 GMT
Content-Language: en_US
{
    "data": [
        {
            "id": 30530030,
            "name": "donation",
            "username": "Ivan",
            "message": "Hello!",
            "amount": 500,
            "currency": "RUB",
            "is_shown": 1,
            "created_at": "2019-09-29 09:00:00",
            "shown_at": null
        }
    ],
    "links": {
        "first": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "last": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://www.donationalerts.com/api/v1/alerts/donations",
        "per_page": 30,
        "to": 1,
        "total": 1
    }
}

Pagination

For the performance reasons DonationAlerts public API paginates the response output. This is because returning the entire data set might be feasible for some queries but prohibitive for others that return a very large amount of data.

API methods that support pagination will return meta and links parts in their response body.

meta
  • Parameter
    Description
  • current_page
    integer
    Current page index
    required
  • from
    integer
    First element index
    required
  • last_page
    integer
    Total number of pages
    required
  • path
    string
    The current path
    required
  • per_page
    integer
    Number of items per page
    required
  • to
    integer
    Last element index
    required
  • total
    integer
    Total number of items
    required
links
  • Parameter
    Description
  • first
    string
    Link to the first page
    required
  • last
    string
    Link to the last page
    required
  • prev
    string, null
    Link to the previous page. Or null if there no previous page
    required
  • next
    string, null
    Link to the next page. Or null if there no next page
    required

To specify a page, add the page parameter to the query.

The following example requests page 2:

curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations?page=2 \
    -H "Authorization: Bearer <token>"

Errors and Statuses

DonationAlerts uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with DonationAlerts' servers.

HTTP Statuses
  • Status
    Description
  • 200 OK
    Standard response for successful HTTP requests
  • 201 Created
    The request has been fulfilled, resulting in the creation of a new resource
  • 202 Accepted
    The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs
  • 204 No Content
    The server successfully processed the request and is not returning any content
  • 400 Bad Request
    The server cannot or will not process the request due to an apparent client error
  • 401 Unauthorized
    Authentication is required and has failed or has not yet been provided
  • 404 Not Found
    The requested resource could not be found but may be available in the future
  • 500 Internal Server Error
    A generic error message, given when an unexpected condition was encountered and no more specific message is suitable

Error example:

HTTP/1.1 401 Unauthorized
Server: nginx/1.13.5
Content-Type: application/json
{
    "message": "Unauthenticated."
}

Limitations

All API requests are subject to rate limits. We limit requests to our HTTP API methods for each application by 60 requests per minute, making it 1 request per second.

Locales

Some of the APIs may support internationalization requiring the developer to specify the locale. All the supported locales are listed below:

  • be_BY - Belarusian;
  • de_DE - German;
  • en_US - English (USA);
  • es_ES - Spanish;
  • es_US - Spanish (USA);
  • et_EE - Estonian;
  • fr_FR - French;
  • he_HE - Hebrew;
  • it_IT - Italian;
  • ka_GE - Georgian;
  • kk_KZ - Kazakh;
  • ko_KR - Korean;
  • lv_LV - Latvian;
  • pl_PL - Polish;
  • pt_BR - Portuguese (Brazil);
  • ru_RU - Russian;
  • sv_SE - Swedish;
  • tr_TR - Turkish;
  • uk_UA - Ukrainian;
  • zh_CN - Chinese.

Currencies

Some of the APIs require currency input or provide currency output in response body.

The list of supported input currencies:

  • EUR - Euro;
  • USD - US Dollar;
  • RUB - Russian Ruble;
  • BRL - Brazilian Real;
  • TRY - Turkish Lira.

The list of supported output currencies:

  • EUR - Euro;
  • USD - US Dollar;
  • RUB - Russian Ruble;
  • BYN - Belarusian Ruble;
  • KZT - Tenge;
  • UAH - Hryvnia;
  • BRL - Brazilian Real;
  • TRY - Turkish Lira.

Request Signatures

Some of the APIs require request signature.

The request signature is a SHA256 hashed string formed from a alphabetically sorted values of request parameters (with every value interpreted as a string) and appended API client secret key to the end.

For example, if request parameters contain:

foo=xyz&bar=abc

Then the signature must be generated as following:

SHA256( abc + xyz + <API client secret> )

Centrifugo

We use Centrifugo to deliver real-time notifications when certain event occurs. It runs as standalone server and takes care of handling persistent connections from application users.

Centrifugo WebSocket connection endpoint:

wss://centrifugo.donationalerts.com/connection/websocket

Subscriptions to Centrifugo's private channels must be properly signed by API application. For the detailed information please read special chapter of Centrifugo documentation about private channel subscriptions.

Steps to Connect to the Centrifugo's WebSocket Server

  • Connecting to the Centrifugo WebSocket Server and obtaining Centrifugo's UUIDv4 Client ID
  • Subscribing to the Private Channels and Obtaining Connection Tokens
  • Connecting to the Private Channels

1. Connecting to the Centrifugo WebSocket Server and obtaining Centrifugo's UUIDv4 Client ID

In order to connect to the Centrifugo's WebSocket Server, first of all, you need to open connection with the Centrifugo WebSocket connection endpoint. Once connection is opened we need to send the message to the WebSocket server. This message must contain message ID and user Centrifugo connection token obtained earlier with the /user/oauth request. Such message must be JSON encoded and should look like this:

{
    "params": {
        "token": "<socket_connection_token>"
    },
    "id": 1
}
                        

In return you'll receive the message with generated Centrifugo's Client ID in form of UUIDv4 and Centrifugo version. This message looks like this:

{
    "id": 1,
    "result": {
        "client": "d558c046-c679-43e3-a62d-65989ab55f7c",
        "version": "2.2.1"
    }
}
                        

2. Subscribing to the Private Channels and Obtaining Connection Tokens

After getting the Centrifugo's UUIDv4 Client ID, you are ready to subscribe to the channels of our choice. Subscribing to the channels can be done with the following request:

POST https://www.donationalerts.com/api/v1/centrifuge/subscribe
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • channels
    string
    Array of private channel names to subscribe to
    required
  • client
    string
    Centrifugo UUIDv4 client ID obtained upon connection to the Centrifugo's WebSocket server
    required
curl \
    -X POST https://www.donationalerts.com/api/v1/centrifuge/subscribe \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"channels":["$alerts:donation_<user_id>"], "client":"<uuidv4_client_id>"}'
  • Query String
    Description
  • channel
    string
    Private channel name
    required
  • token
    string
    Centrifugo connection token. This token can be used to connect to the private channel
    required
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "channels": [
        {
            "channel": "$alerts:donation_<user_id>",
            "token": "<connection_token>"
        }
    ]
}

Response contains array of the subscribed channels and tokens that can be now used to connect to the corresponding private channels.

3. Connecting to the Private Channels

Finally, in order to connect to the subscribed channels, you need to send another message via previously opened WebSocket connection. Each message must contain channel name and connection token, and should look like this:

{
    "params": {
        "channel": "$alerts:donation_<user_id>",
        "token": "<connection_token>"
    },
    "method": 1,
    "id": 2
}

After that, you'll receive confirmation message indicating successful channel connection:

{
   "result": {
        "type": 1,
        "channel": "$alerts:donation_3",
        "data": {
            "info": {
                "user": "1",
                "client": "d558c046-c679-43e3-a62d-65989ab55f7c"
            }
        }
    }
}

Now you are ready to receive real-time event notifications.

Authorization

We use the OAuth 2.0 authorization protocol to issue access to user data. If you are not familiar with the concept of OAuth 2.0, please read RFC 6749 first. All methods of DonationAlerts public API require authorization.

Access Token

Access tokens are the thing that applications use to make API requests on behalf of a user. The access token represents the authorization of a specific application to access specific parts of a user's data. Access tokens must be kept confidential in transit and in storage. The only parties that should ever see the access token are the application itself, the authorization server, and resource server. The application should ensure the storage of the access token is not accessible to other applications on the same device. The access token can only be used over an https connection, since passing it over a non-encrypted channel would make it trivial for third parties to intercept.

Scopes

Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.

The OAuth spec allows the authorization server or user to modify the scopes granted to the application compared to what is requested, although there are not many examples of services doing this in practice. OAuth does not define any particular values for scopes, since it is highly dependent on the service's internal architecture and needs.

DonationAlerts provides 3 scopes to third-party services:

DonationAlerts Scopes
  • Scope
    Description
  • oauth-user-show
    Obtain profile data
  • oauth-donation-subscribe
    Subscribe to new donation alerts
  • oauth-donation-index
    View donations
  • oauth-custom_alert-store
    Create custom alerts
  • oauth-goal-subscribe
    Subscribe to donation goals updates
  • oauth-poll-subscribe
    Subscribe to polls updates

Grant Type: Authorization Code

The authorization code grant type used because it is optimized for server-side applications, where source code is not publicly exposed, and client secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent and receiving API authorization codes that are routed through the user-agent.

Authorization Steps

  • Application registration
  • Authorization request
  • Getting access token
  • Authorization code to access token exchange

1. Application Registration

The application developer must register the application here in order to get tokens. Once the application is registered, the authorization service will issue "client credentials" in the form of a client identifier and a client secret. The client_id is a publicly exposed string that is used by the service API to identify the application, and is also used to build authorization URLs that are presented to users. The client_secret is used to authenticate the identity of the application to the service API when the application requests to access a user’s account, and must be kept private between the application and the API.

2. Authorization Request

The user is given an authorization code link (or redirect) to the https://www.donationalerts.com/oauth/authorize with parameters client_id, redirect_uri, response_type and scope.

GET https://www.donationalerts.com/oauth/authorize
Request Parameters
  • Query String
    Description
  • client_id
    integer
    The client ID received from DonationAlerts
    required
  • redirect_uri
    string
    The URL in your where users will be sent after authorization
    required
  • response_type=code
    string
    Specifies that application is requesting an authorization code grant
    required
  • scope
    string
    A space-delimited list of scopes
    required

When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access to their account. Here is an example authorize application prompt.

3. Getting Authorization Code

If the user allows access to personal data, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code. The authorization code will be available as the value of the code parameter.

4. Getting Access Token

The authorization code must be exchanged for an access token in https://www.donationalerts.com/oauth/token with grant_type, client_id, client_secret, redirect_uri and code parameters.

POST https://www.donationalerts.com/oauth/token
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • grant_type=authorization_code
    string
    The grant type
    required
  • client_id
    integer
    The application ID you received from DonationAlerts
    required
  • client_secret
    string
    The application secret you received from DonationAlerts
    required
  • redirect_uri
    string
    The URL where users will be sent after authorization
    required
  • code
    string
    The authorization code
    required
curl \
    -X POST https://www.donationalerts.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&client_id=<client_id>
&client_secret=<client_secret>&redirect_uri=<redirect_uri>&code=<code>"
  • Query String
    Description
  • token_type
    string
    Token type
    required
  • expires_in
    integer
    Token expiration timestamp
    required
  • access_token
    string
    Access token
    required
  • refresh_token
    string
    Refresh token
    required
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "token_type": "Bearer",
    "access_token": "...msdisYBVnciOiJSUzI1NiIsImp0aSI6IjQxZDU0ZGQ2O...",
    "expires_in": 631151999,
    "refresh_token": "...173da4e0ff4d48c8cbde7a0071f770624a83259f0a11cd02ec1ce71fe924c4..."
}

Refreshing Access Tokens

The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired.

The service will generate and return a new access token if provided data is valid. The server may issue a new refresh token as well, but if the response does not contain a new refresh token the existing refresh token will still be valid.

POST https://www.donationalerts.com/oauth/token
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • grant_type=refresh_token
    string
    The grant type
    required
  • refresh_token
    string
    The refresh_token you received from DonationAlerts
    required
  • client_id
    integer
    The application ID you received from DonationAlerts
    required
  • client_secret
    string
    The application secret you received from DonationAlerts
    required
  • scope
    string
    A space-delimited list of scopes
    required
curl \
    -X POST https://www.donationalerts.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>
&client_secret=<client_secret>&scope=<scope>"
  • Query String
    Description
  • token_type
    string
    Token type
    required
  • expires_in
    integer
    Token expiration timestamp
    required
  • access_token
    string
    Access token
    required
  • refresh_token
    string
    Refresh token
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "token_type": "Bearer",
    "access_token": "...msdisYBVnciOiJSUzI1NiIsImp0aSI6IjQxZDU0ZGQ2O...",
    "expires_in": 631151999,
    "refresh_token": "...173da4e0ff4d48c8cbde7a0071f770624a83259f0a11cd02ec1ce71fe924c4..."
}

Grant Type: Implicit

The implicit grant is similar to the authorization code grant. The token is returned to the client without exchanging an authorization code. This grant is most commonly used for JavaScript or mobile applications where the client credentials can't be securely stored.

Authorization Steps

  • Application registration
  • Authorization request
  • Getting access token

1. Application Registration

The application developer must register the application here in order to get tokens. Once the application is registered, the authorization service will issue "client credentials" in the form of a client identifier and a client secret. The client_id is a publicly exposed string that is used by the service API to identify the application, and is also used to build authorization URLs that are presented to users. The client_secret is used to authenticate the identity of the application to the service API when the application requests to access a user’s account, and must be kept private between the application and the API.

2. Authorization Request

The user is given an authorization request (or redirect) to the https://www.donationalerts.com/oauth/authorize with parameters client_id, redirect_uri, response_type and scope.

GET https://www.donationalerts.com/oauth/authorize
Request Parameters
  • Query String
    Description
  • client_id
    integer
    The client ID received from DonationAlerts
    required
  • redirect_uri
    string
    The URL in your where users will be sent after authorization
    required
  • response_type=token
    string
    Specifies that application is requesting an access token
    required
  • scope
    string
    A space-delimited list of scopes
    required

When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access to their account. Here is an example authorize application prompt.

3. Getting Access Token

If the user allows access to personal data, the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an access token. The access token will be available as the value of the access_token parameter in the hash part of the URL.

API v1

Users

User Profile Information

Obtains user profile information. Requires user authorization with the oauth-user-show scope.

GET https://www.donationalerts.com/api/v1/user/oauth
Request Example Response Parameters Response Example
curl \
    -X GET https://www.donationalerts.com/api/v1/user/oauth \
    -H "Authorization: Bearer <token>"
  • Query String
    Description
  • id
    integer
    The unique and unchangeable user identifier
    required
  • code
    string
    The unique user name
    required
  • name
    string
    The unique displayed user name
    required
  • avatar
    string
    The URL to the personalized graphical illustration
    required
  • email
    string
    The email address
    required
  • socket_connection_token
    string
    Centrifugo connection token
    required
  • Please note that code and name may change at any time upon user rename
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "data": {
        "id": 3,
        "code": "tris_the_jam_master",
        "name": "Tris_the_Jam_Master",
        "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/tris_the_jam_master-profile_image-c084755ce36ab72b-300x300.jpeg",
        "email": "sergey@donationalerts.com",
        "socket_connection_token": "yeJ0eXTYOiJKV1RiLCKhbGciOiJIU4.iJIUfeyJzdeyJzd.GciJIUfiOas_FCvQTYAA8usfsTYYFD"
    }
}

Donations

Donation Alerts List

Obtains array of objects of user donation alerts list. Requires user authorization with the oauth-donation-index scope.

GET https://www.donationalerts.com/api/v1/alerts/donations
Request Example Response Parameters Response Example
curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations \
    -H "Authorization: Bearer <token>"
  • Query String
    Description
  • id
    integer
    The unique donation alert identifier
    required
  • name
    string
    Type of the alert. Always donation in this case
    required
  • username
    string
    The name of the user who sent the donation and the alert
    required
  • message_type
    string
    The message type. The possible values are text for a text messages and audio for an audio messages
    required
  • message
    string
    The message sent along with the donation and the alert
    required
  • amount
    number
    The donation amount
    required
  • currency
    string
    The currency code (ISO 4217 formatted)
    required
  • is_shown
    integer
    A flag indicating whether the alert was shown in the streamer's widget
    required
  • created_at
    string
    The donation date and time (YYYY-MM-DD HH.MM.SS formatted)
    required
  • shown_at
    string, null
    Date and time indicating when the alert was shown (YYYY-MM-DD HH.MM.SS formatted). Or null if the alert is not shown yet
    required
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Sat, 28 Sep 2019 11:19:57 GMT
{
    "data": [
        {
            "id": 30530030,
            "name": "donation",
            "username": "Ivan",
            "message_type": "text",
            "message": "Hello!",
            "amount": 500,
            "currency": "RUB",
            "is_shown": 1,
            "created_at": "2019-09-29 09:00:00",
            "shown_at": null
        }
    ],
    "links": {
        "first": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "last": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://www.donationalerts.com/api/v1/alerts/donations",
        "per_page": 30,
        "to": 1,
        "total": 1
    }
}

Custom Alerts

Custom alerts are the fully content-customizable alerts that allow the developer to create uniquely designed alerts and send it to the streamer's broadcast.

It is required for the streamer to have a variation for the Alerts widget with "Custom alerts" type for custom alerts to display.

Send Custom Alerts

Sends custom alert to the authorized user. Requires user authorization with the oauth-custom_alert-store scope.

POST https://www.donationalerts.com/api/v1/custom_alert
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • external_id
    string
    Up to 32 characters long unique alert ID generated by the application developer
  • header
    string
    Up to 255 characters long string that will be displayed as a header
  • message
    string
    Up to 300 characters long string that will be displayed inside the message box
  • is_shown
    integer
    A value containing 0 or 1. Determines whether the alert should be displayed or not. Default value: 0
  • image_url
    string
    Up to 255 characters long URL to the image file that will displayed along with the custom alert
  • sound_url
    string
    Up to 255 characters long URL to the sound file that will played when displaying the custom alert
curl \
    -X POST https://www.donationalerts.com/api/v1/custom_alert \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "external_id=12&header=Custom%20header&message=Custom%20message&image_url=https%3A%2F%2Fcdn.frankerfacez.com%2Femoticon%2F408827%2F4"
  • Query String
    Description
  • id
    integer
    The unique custom alert identifier
    required
  • external_id
    string, null
    Unique alert ID generated by the application developer. Or null if ID was not provided
    required
  • header
    string, null
    Text that will be displayed as a header. Or null if text was not provided
    required
  • message
    string, null
    Text that will be displayed inside the message box. Or null if text was not provided
    required
  • image_url
    string, null
    URL to the image file that will displayed along with the custom alert. Or null if URL was not provided
    required
  • sound_url
    string, null
    URL to the sound file that will played when displaying the custom alert. Or null if URL was not provided
    required
  • is_shown
    integer
    A flag indicating whether the alert was shown in the streamer's widget
    required
  • created_at
    string
    The date and time (YYYY-MM-DD HH.MM.SS formatted) when custom alert was created
    required
  • shown_at
    string, null
    Date and time indicating when the alert was shown (YYYY-MM-DD HH.MM.SS formatted). Or null if the alert is not shown yet
    required
HTTP/1.1 201 Created
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Thu, 24 Sep 2020 12:04:23 GMT
{
    "data": {
        "id": 24,
        "external_id": "12",
        "header": "Custom header",
        "message": "Custom message",
        "image_url": "https://cdn.frankerfacez.com/emoticon/408827/4",
        "sound_url": null,
        "is_shown": 0,
        "created_at": "2020-09-24 12:04:23",
        "shown_at": null
    }
}

Merchandises

Custom alerts are the fully content-customizable alerts that allow the developer to create uniquely designed alerts and send it to the streamer's broadcast.

It is required for the streamer to have a variation for the Alerts widget with "Custom alerts" type for custom alerts to display.

Create Merchandise

Creates new merchandise. This API is a part of the Merchandise Advertisement API.

POST https://www.donationalerts.com/api/v1/merchandise
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • merchant_identifier
    string
    Merchant's ID on DonationAlerts
    required
  • merchandise_identifier
    string
    Up to 16 characters long unique merchandise ID generated by the merchant
    required
  • title
    array
    Array of up to 1024 characters long strings representing the name of the merchandise in different locales. At minimum, a title for the en_US locale is required
    required
  • is_active
    integer
    A value containing 0 or 1. Determines whether the merchandise is available for purchase or not. Default value: 0
  • is_percentage
    integer
    A value containing 0 or 1. Determines whether the price_service and price_user parameters are recognized as amounts in a currency of the currency parameter or calculated as a percent of the sale's total. Default value: 0
  • currency
    string
    One of the available currencies of merchandise. All revenue calculations will be performed according this value
    required
  • price_user
    number
    Amount of revenue added to streamer for each sale of the merchandise
    required
  • price_service
    number
    Amount of revenue added to DonationAlerts for each sale of the merchandise
    required
  • url
    string
    Up to 128 characters long URL to the merchandise's web page. You may include the {user_id} and {user_merchandise_promocode} patterns in the URL that will be replaced in a UI with the user's ID and user's merchandise promocode
  • img_url
    string
    Up to 128 characters long URL to the merchandise's image
  • end_at_ts
    integer
    Date and time when the merchandise becomes inactive represented as Unix timestamp
  • signature
    string
    Request signature
    required
curl --location --request POST 'https://www.donationalerts.com/api/v1/merchandise' \
--header 'Authorization: Bearer <token>' \
--form 'merchant_identifier=MARKET_GAMES_MAIL_RU' \
--form 'merchandise_identifier=8082' \
--form 'title[en_US]=Credit case' \
--form 'title[ru_RU]=Кредитный кейс' \
--form 'is_active=1' \
--form 'is_percentage=1' \
--form 'currency=USD' \
--form 'price_user=30' \
--form 'price_service=15' \
--form 'url=https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}' \
--form 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--form 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
  • Query String
    Description
  • id
    integer
    Unique merchandise ID on DonationAlerts
    required
  • merchant
    object
    Object carrying identifier and name fields that contains information about the merchant
    required
  • identifier
    string
    Unique merchandise ID on the merchant's online store
    required
  • title
    object
    Object carrying merchandise's titles in different locales
    required
  • is_active
    integer
    A flag indicating whether the merchandise is available for purchase or not
    required
  • is_percentage
    integer
    A flag indicating whether the price_service and price_user parameters should be recognized as absolute values of the currency currency or as a percent of the sale's total
    required
  • currency
    string
    The currency code of the merchandise (ISO 4217 formatted)
    required
  • price_user
    number
    Amount of revenue added to streamer for each sale of the merchandise
    required
  • price_service
    number
    Amount of revenue added to DonationAlerts for each sale of the merchandise
    required
  • url
    string, null
    URL to the merchandise's web page. Or null if URL is not set
    required
  • img_url
    string, null
    URL to the merchandise's image. Or null if image is not set
    required
  • end_at
    string, null
    Date and time indicating when the merchandise becomes inactive (YYYY-MM-DD HH.MM.SS formatted). Or null if end date is not set
    required
HTTP/1.1 201 Created
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Thu, 15 Nov 2020 08:37:37 GMT
{
    "data": {
        "id": 3,
        "merchant": {
            "identifier": "MARKET_GAMES_MAIL_RU",
            "name": "Market games@mail.ru"
        },
        "identifier": "8082",
        "title": {
            "en_US": "Credit case",
            "ru_RU": "Кредитный кейс"
        },
        "is_active": 1,
        "is_percentage": 1,
        "currency": "USD",
        "price_user": 30,
        "price_service": 15,
        "url": "https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}",
        "img_url": "https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png",
        "end_at": null
    }
}

Update Merchandise

Updates merchandise. This API is a part of the Merchandise Advertisement API.

PUT https://www.donationalerts.com/api/v1/merchandise/{:id}
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • merchant_identifier
    string
    Merchant's ID on DonationAlerts
  • merchandise_identifier
    string
    Up to 16 characters long unique merchandise ID generated by the merchant
  • title
    array
    Array of up to 1024 characters long strings representing the name of the merchandise in different locales. At minimum, a title for the en_US locale is required
  • is_active
    integer
    A value containing 0 or 1. Determines whether the merchandise is available for purchase or not. Default value: 0
  • is_percentage
    integer
    A value containing 0 or 1. Determines whether the price_service and price_user parameters are recognized as amounts in a currency of the currency parameter or calculated as a percent of the sale's total. Default value: 0
  • currency
    string
    One of the available currencies of merchandise. All revenue calculations will be performed according this value
  • price_user
    number
    Amount of revenue added to streamer for each sale of the merchandise
  • price_service
    number
    Amount of revenue added to DonationAlerts for each sale of the merchandise
  • url
    string
    Up to 128 characters long URL to the merchandise's web page. You may include the {user_id} and {user_merchandise_promocode} patterns that will be replaced in a UI with the user's ID and user's merchandise promocode
  • img_url
    string
    Up to 128 characters long URL to the merchandise's image
  • end_at_ts
    integer
    Date and time when the merchandise becomes inactive represented as Unix timestamp
  • signature
    string
    Request signature
    required
curl --location --request PUT 'https://www.donationalerts.com/api/v1/merchandise/3' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'title[en_US]=Credit case' \
--data-urlencode 'title[ru_RU]=Кредитный кейс' \
--data-urlencode 'is_active=1' \
--data-urlencode 'is_percentage=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'price_user=30' \
--data-urlencode 'price_service=15' \
--data-urlencode 'url=https://market.games.mail.ru/game/1?product_id=8082' \
--data-urlencode 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--data-urlencode 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
  • Query String
    Description
  • id
    integer
    Unique merchandise ID on DonationAlerts
    required
  • merchant
    object
    Object carrying identifier and name fields that contains information about the merchant
    required
  • identifier
    string
    Unique merchandise ID on the merchant's online store
    required
  • title
    object
    Object carrying merchandise's titles in different locales
    required
  • is_active
    integer
    A flag indicating whether the merchandise is available for purchase or not
    required
  • is_percentage
    integer
    A flag indicating whether the price_service and price_user parameters should be recognized as absolute values of the currency currency or as a percent of the sale's total
    required
  • currency
    string
    The currency code of the merchandise (ISO 4217 formatted)
    required
  • price_user
    number
    Amount of revenue added to streamer for each sale of the merchandise
    required
  • price_service
    number
    Amount of revenue added to DonationAlerts for each sale of the merchandise
    required
  • url
    string, null
    URL to the merchandise's web page. Or null if URL is not set
    required
  • img_url
    string, null
    URL to the merchandise's image. Or null if image is not set
    required
  • end_at
    string, null
    Date and time indicating when the merchandise becomes inactive (YYYY-MM-DD HH.MM.SS formatted). Or null if end date is not set
    required
HTTP/1.1 200 OK
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Thu, 15 Nov 2020 08:37:37 GMT
{
    "data": {
        "id": 3,
        "merchant": {
            "identifier": "MARKET_GAMES_MAIL_RU",
            "name": "Market games@mail.ru"
        },
        "identifier": "8082",
        "title": {
            "en_US": "Credit case",
            "ru_RU": "Кредитный кейс"
        },
        "is_active": 1,
        "is_percentage": 1,
        "currency": "USD",
        "price_user": 30,
        "price_service": 15,
        "url": "https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}",
        "img_url": "https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png",
        "end_at": null
    }
}

Update or Create Merchandise

A combined method which allows to update merchandise, or create if it doesn't exist yet. If preferred, it can be used insdead of separate create and update API methods as this method allows to update a merchandise without need store DonationAlerts merchandise ID. This API is a part of the Merchandise Advertisement API.

PUT https://www.donationalerts.com/api/v1/merchandise/{:merchant_identifier}/{:merchandise_identifier}
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • title
    array
    Array of up to 1024 characters long strings representing the name of the merchandise in different locales. At minimum, a title for the en_US locale is required
    required
  • is_active
    integer
    A value containing 0 or 1. Determines whether the merchandise is available for purchase or not. Default value: 0
  • is_percentage
    integer
    A value containing 0 or 1. Determines whether the price_service and price_user parameters are recognized as amounts in a currency of the currency parameter or calculated as a percent of the sale's total. Default value: 0
  • currency
    string
    One of the available currencies of merchandise. All revenue calculations will be performed according this value
    required
  • price_user
    number
    Amount of revenue added to streamer for each sale of the merchandise
    required
  • price_service
    number
    Amount of revenue added to DonationAlerts for each sale of the merchandise
    required
  • url
    string
    Up to 128 characters long URL to the merchandise's web page. You may include the {user_id} and {user_merchandise_promocode} patterns in the URL that will be replaced in a UI with the user's ID and user's merchandise promocode
  • img_url
    string
    Up to 128 characters long URL to the merchandise's image
  • end_at_ts
    integer
    Date and time when the merchandise becomes inactive represented as Unix timestamp
  • signature
    string
    Request signature
    required
curl --location --request PUT 'https://www.donationalerts.com/api/v1/merchandise/MARKET_GAMES_MAIL_RU/8082' \
--header 'Authorization: Bearer <token>' \
--form 'title[en_US]=Credit case' \
--form 'title[ru_RU]=Кредитный кейс' \
--form 'is_active=1' \
--form 'is_percentage=1' \
--form 'currency=USD' \
--form 'price_user=30' \
--form 'price_service=15' \
--form 'url=https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}' \
--form 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--form 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
  • Query String
    Description
  • id
    integer
    Unique merchandise ID on DonationAlerts
    required
  • merchant
    object
    Object carrying identifier and name fields that contains information about the merchant
    required
  • identifier
    string
    Unique merchandise ID on the merchant's online store
    required
  • title
    object
    Object carrying merchandise's titles in different locales
    required
  • is_active
    integer
    A flag indicating whether the merchandise is available for purchase or not
    required
  • is_percentage
    integer
    A flag indicating whether the price_service and price_user parameters should be recognized as absolute values of the currency currency or as a percent of the sale's total
    required
  • currency
    string
    The currency code of the merchandise (ISO 4217 formatted)
    required
  • price_user
    number
    Amount of revenue added to streamer for each sale of the merchandise
    required
  • price_service
    number
    Amount of revenue added to DonationAlerts for each sale of the merchandise
    required
  • url
    string, null
    URL to the merchandise's web page. Or null if URL is not set
    required
  • img_url
    string, null
    URL to the merchandise's image. Or null if image is not set
    required
  • end_at
    string, null
    Date and time indicating when the merchandise becomes inactive (YYYY-MM-DD HH.MM.SS formatted). Or null if end date is not set
    required
HTTP/1.1 201 Created
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Thu, 15 Nov 2020 08:37:37 GMT
{
    "data": {
        "id": 3,
        "merchant": {
            "identifier": "MARKET_GAMES_MAIL_RU",
            "name": "Market games@mail.ru"
        },
        "identifier": "8082",
        "title": {
            "en_US": "Credit case",
            "ru_RU": "Кредитный кейс"
        },
        "is_active": 1,
        "is_percentage": 1,
        "currency": "USD",
        "price_user": 30,
        "price_service": 15,
        "url": "https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}",
        "img_url": "https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png",
        "end_at": null
    }
}

Merchandise Sale Notifications

Send Sale Alerts

Creates new merchandise sale alert. This API is a part of the Merchandise Advertisement API.

POST https://www.donationalerts.com/api/v1/merchandise_sale
Request Parameters Request Example Response Parameters Response Example
  • Query String
    Description
  • user_id
    integer
    DonationAlerts' user ID to which this merchandise sale referenced
    required
  • external_id
    string
    Up to 32 characters long unique sale ID generated by the developer
    required
  • merchant_identifier
    string
    Merchant's ID on DonationAlerts
    required
  • merchandise_identifier
    string
    Merchant's merchandise ID which was bought by the customer
    required
  • amount
    number
    Grand total of the sale
    required
  • currency
    string
    One of the available currencies of merchandise sale indicating the currency of amount
    required
  • bought_amount
    integer
    Total number of bought items. Default value: 1
  • username
    string
    The name of the customer
  • message
    string
    The message sent by the customer while purchasing the merchandise
  • signature
    string
    Request signature
    required
curl --location --request POST 'https://www.donationalerts.com/api/v1/merchandise_sale' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'user_id=3' \
--data-urlencode 'amount=100' \
--data-urlencode 'currency=RUB' \
--data-urlencode 'merchant_identifier=MARKET_GAMES_MAIL_RU' \
--data-urlencode 'merchandise_identifier=3372' \
--data-urlencode 'external_id=1' \
--data-urlencode 'bought_amount=2' \
--data-urlencode 'username=John' \
--data-urlencode 'message=This is a test message' \
--data-urlencode 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
  • Query String
    Description
  • id
    integer
    The unique merchandise sale alert identifier
    required
  • name
    string
    Type of the generated alert
    required
  • external_id
    string
    Unique sale ID generated by the developer
    required
  • username
    string, null
    The name of the customer. Or null if customer is unknown
    required
  • message
    string, null
    The message sent by the customer while purchasing the merchandise. Or null if text was not provided
    required
  • amount
    number
    Grand total amount of the sale
    required
  • currency
    string
    The currency code of the merchandise sale (ISO 4217 formatted)
    required
  • bought_amount
    inreger
    Total number of bought items
    required
  • is_shown
    integer
    A flag indicating whether the alert was shown in the streamer's widget
    required
  • created_at
    string
    The date and time (YYYY-MM-DD HH.MM.SS formatted) when sale alert was created
    required
  • shown_at
    string, null
    Date and time indicating when the alert was shown (YYYY-MM-DD HH.MM.SS formatted). Or null if the alert is not shown yet
    required
HTTP/1.1 201 Created
Server: nginx/1.13.5
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache, private
Date: Thu, 24 Sep 2020 11:36:14 GMT
{
    "data": {
        "id": 153,
        "name": "merchandise-sale",
        "external_id": 1,
        "username": "John",
        "message": "This is a test message",
        "amount": 100,
        "currency": "RUB",
        "bought_amount": 2,
        "created_at": "2020-11-15 11:36:14",
        "is_shown": 0,
        "shown_at": null
    }
}

Centrifugo Channels

DonationAlerts API offers the variety of Centrifugo channels for receiving real-time event notifications.

You can read more about Centrifugo in the Centrifugo section of this documentation.

Each message sent to a channel carries the reason attribute in addition to the original resource. This attribute describes the event that occured upon message dispatch.

New Donation Alerts

Subscribing to this channel allows to receive new user donation alerts. Requires user authorization with the oauth-donation-subscribe scope.

Centrifugo channel name — $alerts:donation_<user_id>

Messages sent to this channel contain the donation resource represented the same as described in Donations Alerts List.

Donation Goals Updates

Subscribing to this channel allows to receive updates regarding donation goals. Requires user authorization with the oauth-goal-subscribe scope.

Centrifugo channel name — $goals:goal_<user_id>

Messages sent to this channel contain the donation goal resource represented as described below.

Donation Goal Resource
  • Attribute
    Description
  • id
    integer
    The unique donation goal identifier
    required
  • is_active
    integer
    A flag indicating whether the donation goal is in progress or not
    required
  • title
    string
    The donation goal title
    required
  • currency
    string
    The currency code of the donation goal (ISO 4217 formatted)
    required
  • start_amount
    number
    Starting amount of the donation goal
    required
  • raised_amount
    number
    Currently raised amount including the start_amount value
    required
  • goal_amount
    number
    Goal amount of the donation goal
    required
  • started_at
    string
    The date and time (YYYY-MM-DD HH.MM.SS formatted) when donation goal was started
    required
  • expires_at
    string, null
    The date and time (YYYY-MM-DD HH.MM.SS formatted) when donation goal is scheduled to end. Or null if end date is not set
    required

Polls Updates

Subscribing to this channel allows to receive updates regarding polls. Requires user authorization with the oauth-poll-subscribe scope.

Centrifugo channel name — $polls:poll_<user_id>

Messages sent to this channel contain the poll resource represented as described below.

Poll Resource
  • Attribute
    Description
  • id
    integer
    The unique poll identifier
    required
  • is_active
    integer
    A flag indicating whether the poll is in progress or not
    required
  • title
    string
    The poll title
    required
  • allow_user_options
    integer
    A flag indicating whether the poll allows donors to add their own poll options or not
    required
  • type
    string
    Type of the poll that defines how poll winner is calculated. count - finds winner by the most number of donations; sum - finds winner by the most sum of donations
    required
  • options
    array
    Array of available poll options represented as Poll Option resource
    required
Poll Option Resource
  • Attribute
    Description
  • id
    integer
    The unique poll option identifier
    required
  • title
    string
    The poll option title
    required
  • amount_value
    number
    The absolute value of poll option. Depending on poll type the value may contain number or sum of donations
    required
  • amount_percent
    number
    The percent value of poll option relative other poll options
    required
  • is_winner
    integer
    A flag indicating whether the poll option is the poll winner or not. Please note that poll may have multiple winners if maximium amount_value value is shared by several poll options
    required

Advertisement

The Merchandises API is a set of the API methods that allows the merchant to sell their merchandise via DonationAlerts' streamers using a revenue sharing model.
Using the provided API methods it's possible to create and update merchandises, and to notify DonationAlerts when new sale occurs.

Please note that the access to this API is given as per request. For more details about integration contact us via business@donationalerts.com.

Terms dictionary:

  • Merchant - a service or online store integrated with the DonationAlerts' Merchandise API;
  • Merchandise - a product that is available for purchase on the Merchant's online store;
  • Broadcasting Platform - a service that allows its users to livestream media content (for example, Twitch or YouTube);
  • Streamer - a user that livestreams on the Broadcasting Platform and registered on DonationAlerts as a streamer;
  • Customer - a user that intends to purchase Merchant's Merchandise. Most often the Customer is a viewer of the Streamer's livestream.

Merchandises API requires server to server interaction for data exchange between DonationAlerts and Merchant.

To get started with the merchandises sales, the Merchant must be integrated into DonationAlerts. The integration process may vary as it mostly depends on Merchant's possibilities and preferences. For example, it's possible to create, update, or update or create merchandises via API or we may handle it entirely on our side.
But in all occurrences, it is required to integrate with the Send Sale Alerts API as a part of the minimal integration with the Merchandises API, so DonationAlerts can be notified about new sales.

As soon as the merchandise is integrated, it's possible start with the merchandises sales. The image below illustrates the whole process from the start of the purchase procedure to display of new sale alert on the Streamer's livestream:

  1. Customer visits Streamer's livestream on Broadcasting Platform in their web browser or application.
  2. From there Customer transitions to the Merchandise's product webpage hosted on the Merchant's online store. This might be done directly from the Broadcasting Platform if the Streamer placed the Merchandise's URL there (2.a) or by going through the Streamer's donation page on DonationAlerts (2.b, 2.c) as all of the Streamer's merchandises are listed there. Optionally, Merchandise's URL may carry DonationAlerts' user ID or the Streamer's promocode in its query parameters, so Merchant may easily recognize which Streamer's referral link was used.
  3. On the Merchant's online store the Customer goes through the usual checkout process and being redirected to the Payment Processor to complete the purchase.
  4. After the purchase the Customer is redirected back to the Merchant's online store and Payment Processor notifies the Merchant about new purchase.
  5. Merchant notifies DonationAlerts about new purchase using Send Sale Alerts API.
  6. Upon new sale notification DonationAlerts adds revenue to the Streamer's balance on DonationAlerts and generates new merchandise sale alert that is being sent to the Streamer's alerts widget.
  7. The Streamer's alerts widget receives merchandise sale alert and displays it while Streamer's broadcasting software captures the content of the alerts widget and transmits it to the Broadcasting Platform along with other media content.

Plugins & Libraries

For your convenience we have created various plugins and libraries that will help you to quick start with various parts of DonationAlerts API in different development environments.

Unreal Engine 4 Plugin

Allows to easily authorize the player and send custom alerts. The plugin is available on its GitHub page: https://github.com/ufna/DonationAlerts.

Usage

Please register your OAuth application and set up the plugin:

How to authenicate user:

How to send custom alert:

How to react to donation events:

How to react to donation goal events:

How to react to poll events:

By authorizing, you confirm that you have read carefully and agree to our Terms of Service and our Privacy Policy.