Table of Contents
The Roku Web Service API allows subscribers who signed up on Roku to use your service on other platforms. For instance, this API can be used to determine whether a subscription on Roku is still valid so the subscriber can be granted access to a platform other than Roku. Among other features, this REST API provides functionality for transaction events such as verifying purchases, canceling subscriptions, issuing credits or refunds, and updating billing cycles.
The Web Service API supports Roku billing services. After setting up your channel's in-channel products as described in Roku Billing and In-Channel Purchasing, you can use the Web Service API at runtime to verify entitlement and manage customer transactions.
Setting Up Roku Web Services
Before using the Web Service API, use the Developer Dashboard to find your partner API key. On the Developer Dashboard Web API Settings screen, Roku assigns your partner API key as the "Roku API Key." You cannot change your partner API key. Keep it safe but accessible because you must use it to perform transactions.
On the Web API Settings screen you can set a range of IP addresses that transaction service requests can come from. Doing so prevents requests from other IP addresses that don't use your partner API key. A request is valid if Roku receives it from the range of IP addresses specified, or if no range is specified, a request is valid from any IP address using your partner API key.
Also on the Web Settings API screen, you specify the URL endpoint at which you will receive push notifications for transaction events such as purchases, cancellations, refunds, and credits.
Note: If the endpoint to receive push notifications fails for a specific message for three consecutive days, Roku stops sending that notification.
Note: Once an endpoint has failed for 100 messages within 10 days, the endpoint is blacklisted. Roku stops sending all notifications and checks the box Stop sending billing notifications on the Web API Settings page. When the endpoint is valid again and can receive push notifications, you can uncheck Stop sending billing notifications.
See Developer Dashboard for an overview of available features.
API Calls
The Web Service API endpoint is https://apipub.roku.com.
You can use either XML or JSON format for your requests.
- To use JSON, include the following header in the request:
accept: application/json - To use XML, include the following header in the request:
accept: text/xml
Validate Transaction
This process validates a transaction that was returned from a channel or product purchase in the Channel Store. It also helps in optimizing the process of dunning.
Dunning is the process of methodically communicating with the users their subscription expiration status and re-attempting a charge to their MOPs to ensure collection of payment.
isEntitled is a parameter that is implemented to determine a user’s subscription eligibility and supplement validating a Channel Store transaction.
To use the parameter, the entitlement service that the channel has should run a nightly sync with the Roku Channel Store channel in which it iterates all expired subscriptions and calls validate-transaction, that passes the stored transaction ID for the subscription. The channel then needs to read isEntitled in their entitlement decision making (See Response example below).
It is highly recommended for channels with in-channel products to use isEntitled as it ensures that the users don't find themselves in a situation where they are paying for a subscription to a service that is not authenticating them. Moreover, it can possibly increase customer retention for the channel.
When isEntitled is used by the channel, both the expirationDate and isEntitled should be compared to determine the accurate state of a user’s subscription status. In general, use the isEntitled field to determin whether to entitle a user. The cancelled and expirationDate fields are used to determine when to check again.
cancelled and expirationDate fields. Just use the isEntitled flag and entitle the user until the next check. | Subscription State | isEntitled | cancelled | expirationDate | Expected Action |
|---|---|---|---|---|
| Active subscription | True | False | Future date | Entitle the user. Check again a day after the expirationDate |
| Actively cancelled subscription with expiration date in the future | True | True | Future date | Entitle the user, check again a day after the expirationDate before removing entitlement on your side. You should see isEntitled set to False, in which case you can remove entitlement. isEntitled may return True if the user changed their mind and resubscribed before the expiration date, in which case they should be treated as having an active subscription. |
| Actively cancelled subscription on expiry date. (Before subscription expiration timestamp) | True | True | Current date | Entitle user. Check again the next day. |
| Actively cancelled subscription on expiry date. (After subscription expiration timestamp) | False | True | Current date | Remove entitlement. Cancel subscription. |
| Actively cancelled subscription after expiry date | False | True | Past date | Remove entitlement. Cancel subscription. |
| Subscription in dunning | True | False | Current or Past date | Entitle user. Check again next day. |
| Subscription after unsuccessful dunning. (Passively canceled subscription) | False | True | Past date | Remove entitlement. Cancel subscription. |
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
Heading:
|
Response example:
|
Validate Refund
Validates a transaction that was returned from a channel or product purchase in the Channel Store.
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
Heading:
Response example:
|
Cancel Subscription
Cancels the subscription that corresponds to the transactionId. The channel associated with the transactionId must be owned by the developer associated with partnerAPIKey.
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
Heading:
Request example:
|
Response example:
|
Refund Subscription
Refunds the subscription that corresponds to the transactionId. The channel associated with transactionId must be owned by the developer associated with partnerAPIKey. A refundId is returned to validate if needed at a later date.
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
Heading:
Request example:
|
Response example:
|
Update Billing Cycle
Updates the billing cycle of a subscription with the provided transactionId. The subscription must be owned by the developer that owns the included partnerAPIKey. The newBillCycleDate must be included in an ISO-8601 format.
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
Heading:
Request example:
|
Response example:
|
Issue Service Credit
Used to issue a service credit to a particular rokuCustomerID. The channel/product must be owned by the developer that owns the included partnerAPIKey.
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
If the service credit is for a channel, there must be an included channelID. For an in-app product, there must be both a channelID and productID. The response will include a partnerReferenceId that can be used later to find the service credit in the Roku system.
Heading:
Request example:
|
Response example:
|
Push Notifications
Push notifications are sent from Roku to your listener web server. The push notification contains a response key. You then send back a notification response containing the response key.
You can receive four types of push notifications:
A sample response for each type of push notification is given below.
Security Example
To ensure security, Roku sends a responseKey as shown in the push example below. You must return this responseKey in the response content. Neither of these have a cryptographic signature.
Before downloading the content, Roku checks that the size of your responseKey matches the size of the responseKey Roku sent to you. This prevents hackers from responding with overwhelmingly large chunks of data attempting to crash the Roku Web Service.
Additionally, you are required to send an ApiKey header with the value containing your partner API key that was issued on the Developer Dashboard.
Note: Your partnerAPIKey can be found on the Web API Settings screen in the field Your Roku API Key.
The ApiKey header must have a content length of 32. When sending the notification, the subscriber cannot redirect in any way. If a redirect attempt is made, the request will fail. The request times out after 10 seconds.
Push Example
|
Response Example
|
Example of Each Push Notification Response
Sale (purchase) Response Example
|
Cancellation Response Example
|
Refund Response Example
|
Credit Response Example
|
