Skip to end of metadata
Go to start of metadata

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 API provides functionality for transaction events such as sales, canceling subscriptions, issuing credits or refunds, and updating billing cycles.

 

Table of Contents



Setting Up Roku Web Services

All transaction service requests require a Roku API Key assigned to each Roku developer. The API key can be retrieved from the Web API Settings page on the Developer Dashboard.

You can also set a range of IP addresses that transaction service requests can come from. A request is valid only if Roku receives it from the range of IP addresses specified. If no range is specified, a request  is valid from any IP address using your Roku API Key.

You can specify a URL endpoint to receive push notifications for transaction events such as purchases, cancellations, refunds, and credits.

If the endpoint to receive push notifications fails consecutively for three days, Roku stops sending notifications and checks the box Stop sending billing notifications on the Web API Settings page. When the endpoint is valid and can receive push notifications again, you can uncheck Stop sending billing notifications. If the endpoint to receive notifications fails for 10 days and with 100 failed messages, your endpoint is blacklisted.


 

See Developer Dashboard for an overview of available features.

API Calls

The Web Service API calls are all located at https://apipub.roku.com. You do not need a Roku certificate to use them.

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

Validates a transaction that was returned from a channel or product purchase in the channel store.

Heading:

Response example: 

 

<result>
  <transactionId>{transactionid}</transactionId>
  <purchaseDate>2012-07-22T14:59:50</purchaseDate>
  <channelName>123Video</channelName>
  <productName>123Video Monthly Subscription</productName>
  <productId>NETMONTH</productId>
  <amount>9.99</amount>
  <currency>USD</currency>
  <quantity>1</quantity>
  <rokuCustomerId>abcdefghijklmnop</rokuCustomerId>
  <expirationDate>2012-08-22T14:59:50</expirationDate>
  <originalPurchaseDate>2010-08-22T14:59:50</originalPurchaseDate>
  <status>Success</status>
  <errorMessage>error_message</errorMessage>
</result>

 

Validate Refund

Validates a transaction that was returned from a channel or product purchase in the channel store.

Heading: 

Response example:

 

<result>
  <transactionId>{transactionid}</transactionId>
  <purchaseDate>2012-07-22T14:59:50</purchaseDate>
  <channelName>123Video</channelName>
  <productName>123Video Monthly Subscription</productName>
  <productId>NETMONTH</productId>
  <amount>9.99</amount>
  <currency>USD</currency>
  <quantity>1</quantity>
  <expirationDate>2012-08-22T14:59:50</expirationDate>
  <originalPurchaseDate>2010-08-22T14:59:50</originalPurchaseDate>
  <status>Success</status>
  <errorMessage>error_message</errorMessage>
</result>

 

Cancel Subscription

Cancels the subscription that corresponds to the transactionId. The channel associated with the transactionId must be owned by the developer associated with Roku API Key.

Heading: 

Request example:

 

content-type: text/xml
accept: text/xml
<cancel>
  <rokuAPIKey>{apikey}</rokuAPIKey>
  <transactionId>{transactionId}</transactionId>
  <cancellationDate>2012-08-22T14:59:50</cancellationDate>
  <partnerReferenceId>{partnerReferenceId}</partnerReferenceId>
</cancel>

 

Response example:

 

<result>
  <status>Success</status>
  <errorMessage>error_message</errorMessage>
</result>

 

Refund Subscription

Refunds the subscription that corresponds to the transactionId. The channel associated with transactionId must be owned by the developer associated with Roku API Key. A refundId is returned to validate if needed at a later date.

Heading:

Request example: 

 

content-type: text/xml
accept: text/xml
<cancel>
  <rokuAPIKey>{apikey}</rokuAPIKey>
  <transactionId>{transactionId}</transactionId>
  <amount>2.99</amount>
  <partnerReferenceId>{partnerReferenceId}</partnerReferenceId>
  <comments>Customer was not impressed</comments>
</cancel>

 

Response example: 

 

<result>
  <status>Success</status>
  <errorMessage>{error message goes here}</errorMessage>
  <refundId>{refundId}</refundId>
</result>

 

Update Billing Cycle

Updates the bill cycle of a subscription with the provided transactionId. The subscription must be owned by the developer that owns the included rokuAPIkey. The newBillCycleDate must be included in an ISO-8601 format.

Heading: 

Request example: 

 

content-type: application/json
accept: application/json
{
  "rokuAPIKey":"02E763BE3642C0459CF79F5E011CB1CE5642",
  "newBillCycleDate":" 2014-03-28",
  "transactionId":"1C63E500EF094DB4A83CA2CF00B7EB4E"
}

 

Response example:

 

{
  "errorCode":null,
  "errorDetails":null,
  "errorMessage":"",
  "status":0
}

 

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 rokuAPIKey. 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: 

 

accept: application/json
content-type: application/json
{
  "rokuAPIKey":"02E763BE3642C0459CF79F5E011CB1CE5642",
  "amount":5.00,
  "channelId":"10081",
  "comments":"This is sample json",
  "partnerReferenceId":" ",
  "productId":" ",
  "rokuCustomerId":"AC4D2FD61F624451A61AQ2CF00A766A1"
}

 

Response example:

 

{
  "errorCode":null,
  "errorDetails":null,
  "errorMessage":"",
  "status":0,
  "ReferenceId":"1409"
}

 

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

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 Roku API key that was issued on the developer site. It 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

 

{
"customerId": "abcdd8c616cc4802989da2d800cfabcd",
"transactionType": "Credit",
"transactionId": "1243",
"channelId": "484",
"channelName": "Ssaldsdld",
"productCode": "abcdabcdd68d4ff3abcd",
"productName": "Monthly Sub",
"price": 5.00,
"total": 5.00,
"currency": "usd",
"partnerReferenceId": "prefid",
"comments": "Service Credit Test",
"eventDate": "2017-11-20T20:34:21.1781901Z",
"responseKey":"abcdabcd6b1649f681a408f1beebabcd"
}

 

Response Example

 

HTTP/1.1 200 OK
ApiKey: {rokuAPIKey}
Content-Length: 32
abcdabcd6b1649f681a408f1beebabcd

 

Example of Each Push Notification Response

 Sale (purchase) Response Example

 

{
  "customerId":"ac4d2fd61f624451a61aa2cf00a766a1",
  "transactionType":"Sale",
  "transactionId":"aa3f3a2479ea4e0c88d9a2d500f33e74",
  "channelId":"26558",
  "productCode":"testProd123",
  "price":0.99,
  "tax":0.00,
  "total":0.99,
  "currency":"usd",
  "comments":"New order processed.",
  "eventDate":"2014-02-17T22:45:37.496125Z",
  "responseKey":"659a9e3f6b1649f681a408f1beeb2766"
}

 

 Cancellation Response Example

 

{
  "customerId""6a4d984e7aee47d18975a2d800cb707b",
  "transactionType""Cancellation",
  "transactionId""260a7b6d8e4a4e7b8b0ba2d800cb7142",
  "channelId""445",
  "productCode""fb435917cefc4f66b36c",
  "productName":"Monthly Sub",
  "expirationDate""2014-02-20T20:20:42.6473452Z",
  "originalTransactionId""a82e4abdab0247fb9a2ca2d800cb712d",
  "originalPurchaseDate""2014-02-20T20:20:42",
  "partnerReferenceId""CANCELTESTNOTIFICATION",
  "comments":"Cancellation for Monthly Sub",
  "eventDate""2014-02-20T20:20:42.6903495Z",
  "responseKey":"c1a73677590948e68215586dfa9455b5"
}

 

 Refund Response Example

 

{
  "customerId":"ac4d2fd61f624451a61aa2cf00a766a1",
  "transactionType":"Refund",
  "transactionId":"970625d44a544b78964ba2d6011231bd",
  "channelId":"26558",
  "productCode":"testProd123",
  "price":-0.99,
  "tax":0.00,
  "total":-0.99,
  "currency":"usd",
  "originalTransactionId":"dccc31583aa1441e8c76a2d600b28716",
  "originalPurchaseDate":"2014-02-18T18:49:59",
  "partnerReferenceId":"test",
  "comments":"test",
  "eventDate":"2014-02-19T00:38:20.231375Z",
  "responseKey":"c1a73677590948e68215586dfa9455b5"
}

 

 Credit Response Example

 

{
  "customerId""bbd2d8c616cc4802989da2d800cf2b81",
  "transactionType""Credit",
  "transactionId""1243",
  "channelId""484",
  "channelName""StwzAbNxMbX779Ia",
  "productCode""f478e3a9d68d4ff390bb",
  "productName""Monthly Sub",
  "price"5.00,
  "total"5.00,
  "currency""usd",
  "partnerReferenceId""prefid",
  "comments""Service Credit Test",
  "eventDate""2014-02-20T20:34:21.1781901Z",
  "responseKey":"659a9e3f6b1649f681a408f1beeb2766"
}

 

 

  • No labels