Using In-Channel Purchasing with your Roku Channel


This Instant TV Channel Help article applies only to Developer SDK Roku channels. Roku does not support In-Channel Purchasing in Direct Publisher channels yet.

The In-Channel Purchase feature allows a Roku channel to support one-time and subscription purchases entirely within a Roku channel. Product selection and payment authorization are all performed on-screen using the Roku remote control. All payments are processed through Roku Billing Services, and Roku deposits sales revenue directly to your PayPal account. Each product offered for purchase in a Roku channel has a unique Product Identifier configured in your Roku Developer Account. Products can be individual videos, groups of videos, or entire channels. During the purchase process the viewer is prompted to enter their Roku PIN number to authorize a one-time or recurring credit card charge. If the purchase is successful, then any product in the channel (or any channel in the same Roku Developer Account) with the corresponding Product Identifier will be available to the viewer.

• In order to use the In-Channel Purchase feature with your Roku channel, you must be enrolled in the Roku Billing Services Program. Visit the Roku Billing Services page at www.roku.com/billing for additional information.
• Your Instant TV Channel account Developer Mode must be set to Advanced in order to view or change In-Channel Purchase related settings. You can change the Developer Mode from the Instant TV Channel Account page.
• Your channel must be a Commercial channel type. Free and Unlimited channel types do not support In-Channel Purchasing.
• Your channel must either be newly created, or be at Update #285 or higher in order to use the In-Channel Purchase feature for your Roku channel.
• Video and audio content items created in channels older than Update #285 do not have support for user-defined Springboard buttons or Product parameters. Older content items will need to be re-entered as new items in order to be used with In-Channel Purchasing.

Products available for purchase with the In-Channel Purchase feature currently include:
  • ad removal - Remove video ads from a specific content item or items.
  • content - Allow a specific content item or items to be played, with or without video ads.
  • content without video ads - Allow a specific content item or items to be played with the video ads removed.
  • quality - Allow access to HD bitrate streaming for a specific content item or items. (Streams are tagged as HD within Instant TV Channel by setting the Stream Quality parameter to "True".)
  • quality without video ads - Allow access to HD bitrate streaming for a specific content item or items with the video ads removed.
  • other - Allow a purchase to be made that has no effect on what content item can be played. For example a donation or contribution.
Purchase Types are determined by the Product settings in your Roku Developer Account. Each Product has a single Purchase Type. Available Purchase Types currently include:
  • One-Time Purchase - A one-time non-recurring purchase.
  • One-Time Purchase, Consumable - Allows multiple purchases of the same Product. Not typically used for video content.
  • Monthly Subscription - A monthly recurring purchase.
  • Yearly Subscription - A yearly recurring purchase.

More than one product can be purchased for a single content item. For example a content item might have two separate product purchase buttons, one for ad removal and another for HD quality. The two products, ad removal and HD quality, could be purchased separately or purchased together:

Example Content Item with 2 Products
Product Purchased Services Available Services Not Available
None SD video streaming. HD video streaming, video ad removal.
"Ad Removal" Only SD video streaming, video ad removal. HD video streaming.
"Quality Content" Only SD and HD video streaming. Video ad removal.
Both "Ad Removal" and "Quality Content" SD and HD video streaming, video ad removal.  

Below is a complete matrix of all possible purchase combinations. Note that the availability of one product can affect the services provided by another product. For example, if the "content" product is offered by itself, the viewer has both HD and SD streams available after purchasing the product. But if the "quality content without video ads" product is offered along with the "content" product, then the "content" product only provides an SD stream, and the viewer must purchase the additional "quality content without video ads" product in order to view the HD stream.

In-Channel Purchase Matrix
If multiple Products Purchase Types are available for a single content item:
Product Purchase Type Purchased Available But Not Purchased
Remove Ads Allow HD Allow SD Remove Ads Allow HD Allow SD
ad removal yes          
content     yes   no, if not already yes no, if not already yes
content without video ads yes   yes   no, if not already yes no, if not already yes
quality content   yes yes   no, if not already yes  
quality content without video ads yes yes yes   no, if not already yes  
other            
If neither yes nor no after all available Product Purchase Types for a Content Item are considered:
  Remove Ads Allow HD Allow SD
Default Settings no yes yes

Walkthrough

Let's walk through the steps required to set up a single video content item with both an "ad removal" product and a "quality content" (HD) product. This will provide the viewer with 4 choices for watching the content item:

  • Don't purchase anything and watch the stream in SD with video ads.
  • Purchase just the "ad removal" product and watch the stream in SD without video ads.
  • Purchase just the "quality content" product and watch the stream in HD with video ads.
  • Purchase both products and watch the stream in HD without video ads.

The walkthrough will consist of several parts:

  • Add Products to your Roku Developer Account
  • Add a Test User to your Roku Developer Account (optional)
  • Add Purchase Buttons and Products to your Instant TV Channel Videos
  • Set up an S3 Transaction Bucket (optional)

Add Products to your Roku Developer Account

  1. Log into your Roku Developer Account and click "Manage My In-Channel Products". This should display the "Manage My In-Channel Products" page.

    If you not see the "Manage My In-Channel Products" link then you'll need to sign up for Roku Billing Services. There should be a link on the main page of your Roku Developer Account that allows you to sign up, or visit the Roku Billing Services page at www.roku.com/billing.

  2. On the "Manage My In-Channel Products" page, click the "Add a Product" button. This should display the "Add an In-Channel Product" page.
  3. From the list of channels, select the channel or channels to which you wish to add this product.
  4. Enter a Product Name of "View without Ads", or chose your own Product Name if you'd like. Once this name has been entered it cannot be changed. The Product Name will be shown on the receipt that Roku emails to a purchaser, and it can optionally be used in the on-screen receipts in your Roku channel. The same Product Name can be used for multiple products.
  5. Enter an Identifier of "AD-1", or chose your own Identifier if you'd like. This is an order code that will be used in your Roku channel to identify this specific product. If you have multiple In-Channel Products, each product must have a unique Identifier. The Identifier is not visible to the purchaser.
  6. Enter a Purchase Type. The following types are available:
    • One-Time Purchase - This Purchase Type is used to allow a subscriber to make a one-time non-recurring purchase.
    • One-Time Purchase, Consumable - This Purchase Type allows the subscriber to make multiple purchases. It is not usually used for products such as video content or ad removal, but it could be used for donations or contributions.
    • Monthly Subscription - This Purchase Type causes the subscriber's account to be charged each month on a recurring basis. It is often used for subscription-based video content.
    • Yearly Subscription - This Purchase Type causes the subscriber's account to be charged each year on a recurring basis.
  7. Leave Quantity set at the default value of "1"
  8. Leave Internet Connection Required at the default setting of "Yes"
  9. Leave Requires Additional Purchase at the default setting of "No"
  10. Change Cleared for Sale to "Yes"
  11. Select a Price Tier for the product. This is the amount that each subscriber will be charged when purchasing your product. If your channel is available in multiple geographic regions then several different local currencies may be displayed for each tier.
  12. Click the "Create" button. This should return you to the "Manage My In-Channel Products" page.
  13. Click "Submit for review" for the product that you just created.
  14. Repeat each of the above steps to create another In-Channel Product, except this time use a Product Name of "View in HD" and an Identifier of "HD-1".
  15. This step is extremely important: After your products have been submitted for review, you must also send an email to developer@roku.com to notify Roku that you have In-Channel Products waiting for approval. You should receive an email in a few days confirming that your products have been reviewed and approved.

Add a Test User to your Roku Developer Account

A test account is used so that you can make on-screen test purchases from your Roku channel without charges being applied to your credit card.

• Setting up a test user is optional.
• Your In-Channel Purchases will be processed correctly even if you do not set up a test user, however any purchases that you make to test your Roku channel will result in actual credit card charges.
  1. From the main page of your Roku Developer Account, click "Manage Test Users". This should display the "Manage Test Users" page.
  2. Click "Add New Test User".
  3. Enter the email address of the test user. This must be the same email address that is associated with the Roku device that you will be testing with.
  4. Select the Roku channels in which you want to allow the user to make test purchases.
  5. Click the "Add" button.

Add Purchase Buttons and Products to your Instant TV Channel Videos

• Video content items created in channels older than Update #285 do not have support for user-defined Springboard buttons such as the Purchase button, and will need to be re-entered as new items in order to use with In-Channel Purchasing.
  1. From the Instant TV Channel "Content" page, select the video content item to which the Purchase buttons will be added.
  2. Scroll down the parameter list until you see the Button parameters ("Button 1", "Button 2", etc).
  3. Click the New button located on the highest numbered Button parameter block. This will create a new Button parameter block.
  4. Change the new button's Action parameter from "New" to "Purchase".
  5. Change the "Purchase" button's Label parameter to "Remove ads for 99 cents". Instead of "99 cents" you should use whatever price tier you previously selected for ad removal in your Roku Developer Account.
  6. Because this is a one-time purchase, leave the Button Display parameter set at "hide if this product is purchased". This will cause the button to be hidden after a purchase has been made.
  7. Enter a Purchase button Identifier of "AD-1", or whatever ad removal Identifier you previously entered in the In-Channel Products page of your Roku Developer Account.
  8. Enter a Purchase button Product Name of "Ad Removal". This name can be displayed in the on-screen Receipts available to your subscribers. If Product Name is blank then the Product Name entered in the In-Channel Products page of your Roku developer account will be used for on-screen receipts.
  9. Leave the After Purchase parameter set at "play this content item". This will cause the video to play immediately after a successful purchase. If the purchase is not successful then the Springboard screen will be redisplayed.

Editing a Purchase Button
  1. Click the New button located on the Purchase button parameter block. This will create another new Button parameter block.
  2. Change this new button's Action parameter from "New" to "Purchase".
  3. Change the new "Purchase" button's Label parameter to "View in HD for 99 cents". Instead of "99 cents" you should use whatever price tier you previously selected for "View in HD" in your Roku Developer Account.
  4. As before, leave this button's Button Display parameter set at "hide if this product is purchased".
  5. Enter a Purchase button Identifier of "HD-1", or whatever HD Identifier you previously entered in the In-Channel Products page of your Roku Developer Account.
  6. Enter a Purchase button Product Name of "View in HD".
  7. As before, leave the After Purchase parameter set at "play this content item".
  8. Optionally change the Purchase button's location relative to the other buttons by clicking the up ⇧ or down ⇩ arrows next to each button.
  9. Scroll lower in the video's parameter list until you locate the Product block containing the Product Identifier and Product Purchase Type.
  10. Set the Product Identifier to the same value as the Purchase button Identifier, "AD-1".
  11. Set the Product Purchase Type to "ad removal".

    The Purchase Type of "ad removal" is now tied to the "AD-1" Identifier for this video content item. If this video is played and the "AD-1" product has been previously purchased, all ads will be removed from the video.


Editing a Product
  1. Click the Product New button to create a second Product, then repeat each of the above steps once more, except this time use a Product Identifier of "HD-1" and a Product Purchase Type of "quality content".

    The Purchase Type of "quality content" is now tied to the "HD-1" Identifier for this video content item. If this video is played and the "HD-1" product has been previously purchased, all streams in this video that have the Quality parameter set to "True" will playable.

Set up an S3 Transaction Bucket

An S3 bucket can be set up which will contain a file for each In-Channel Purchase transaction. The files in the transaction bucket can be used to reconcile the transaction information in your Roku Developer Account. If you collect user data (email and street addresses) with each purchase, the user data will be stored in the bucket as part of the purchase's transaction file. The Instant TV Channel "Roku Billing" page allows you to view the contents of the transaction files, or you can download the S3 bucket contents for processing with your own application.

• Setting up an S3 transaction bucket is optional.
• Your In-Channel Purchases will be processed correctly even if you do not set up an S3 transaction bucket, however no user data will be saved.
• The transaction files are written directly into the S3 transaction bucket by each Roku device as a purchase is made, and may be missing if there are network problems at the time of the purchase that prevent the Roku device from reaching Amazon.
• Any valid purchase will always have a transaction record available in your Roku Developer Account.
  1. Click on the "Roku Billing" link on the left side of the Instant TV Channel page.
  2. Copy and paste the 36-character "Roku API Key" from the "Web API Settings" page in your Roku Developer Account to the Roku API Key parameter on the Instant TV Channel "Roku Billing Settings" page.
  3. Go to the S3 section of your AWS (Amazon Web Services) control panel and create a new S3 bucket, named something like "my-transaction-bucket". You will use the bucket name in several of the following steps.
    • The Region must remain at the default value of "US Standard".
    • This should be a private bucket that is not web enabled.
    • This bucket will only be used to contain transaction information for Roku In-Channel Purchases and should not be used for Instant TV Channel Configuration File or Content storage.
    • Use only lower-case characters, digits, and dashes in your bucket name. Instant TV Channel does not support the use of upper-case characters or other symbols in bucket names.

      Good Bucket Name: transaction-bucket
      Good Bucket Name: transaction123
      Bad Bucket Name: transaction.bucket (contains unsupported period character ".")
      Bad Bucket Name: transaction+123 (contains unsupported plus character "+")
      Bad Bucket Name: Transaction-Bucket (contains upper-case characters "T" and "B")
  4. Go to the IAM (Identity and Access Management) section of your AWS control panel where we will create a new IAM identity and keys.
    1. Click the Policies link on the left side of the page.
    2. Click the Create Policy button near the top of the page.
    3. Click the Select button to the right of "Create Your Own Policy".
    4. Provide a Policy Name, for example "my-transaction-policy".
    5. Copy the security policy below and paste into the Policy Document box, replacing "my-transaction-bucket" with the name of the bucket you just created.
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "s3:*"
            ],
            "Resource": [
              "arn:aws:s3:::my-transaction-bucket",
              "arn:aws:s3:::my-transaction-bucket/*"
            ]
          }
        ]
      }
    6. Click the Create Policy button near the bottom of the page.
    7. Click the Groups link on the left side of the page.
    8. Click the Create New Group button near the top of the page.
    9. Provide a group name, for example "my-transaction-group", then click the Next Step button near the bottom of the page.
    10. The "Attach Policy" page is displayed. Scroll down the list of policies until the "my-transaction-policy" policy that you just created is visible. You may need to scroll through a large number of built-in AWS policies until your policy is visible.
    11. Click the check-box to the left of your policy name, making sure that no other check-boxes are checked, then click the Next Step button near the bottom of the page.
    12. Click the Create Group button near the bottom of the page.
    13. Click the Users link on the left side of the page.
    14. Click the Create New Users button near the top of the page.
    15. Enter a new user name into box #1, for example "my-transaction-user".
    16. Click the Create button near the bottom of the page.
    17. Click either Show User Security Credentials or Download Credentials to copy and save the Access Key ID and Secret Access Key. These keys will be used exclusively for your Transaction bucket. They cannot be used to access any other AWS bucket or service. Make sure that you save the keys for future use, Amazon will not display them again. If you misplace the keys you will have to create a new IAM user.
    18. After copying the Security Credentials, click the Close button near the bottom of the page. You may need to click this button twice.

      At this point we have a new IAM user and a new IAM group - the user has the keys and the group has the security policy. The next steps will add the user to the group so that the keys and security policy will be associated with each other. This will allow the keys to be used in the Roku channel to access the S3 bucket specified by the security policy.

    19. Click the Users link on the left side of the page.
    20. Click the checkbox next to the User that you just created.
    21. Click the User Actions button near the top of the page and select "Add User to Groups".
    22. Click the checkbox next to the Group that you just created.
    23. Click the Add to Groups button near the bottom of the page.
  5. Enter the name of the Transaction bucket that you just created into the Instant TV Channel Transaction Bucket Name parameter on the "Roku Billing Settings" page.
  6. Leave the Transaction Prefix or Folder Name parameter blank. You can use this later if you wish to set up separate folders for multiple Roku channels.
  7. Enter the Access Key ID that you just created into the Instant TV Channel Transaction Bucket Access Key ID parameter.
  8. Enter the Secret Access Key that you just created into the Instant TV Channel Transaction Bucket Secret Access Key parameter.
  9. Click the TEST S3 TRANSACTION STORAGE button to verify that the bucket name and S3 keys are correct. If this test fails, do not proceed until the problem is resolved.
  10. The default "request" setting of the User Data parameter will cause the Roku device to ask the user for permission to share their email and street address before a purchase is made. If the user agrees, the user data will be added to the transaction receipt stored in the S3 bucket. If the user does not agree to share their data the purchase will still proceed normally.

    If you do not wish to ask the user for their email address and street address when making a purchase, change the User Data parameter to "none".

    If you want to require the user to share their email address and street address when making a purchase, change the User Data parameter to "require". If the user does not agree to share their data then the purchase will be cancelled. This setting is not recommended, as it may result in lost sales.

  11. Leave the Use Store Catalog setting at its default value of "True". This value only needs to be changed if you have a very large number of In-Channel Products assigned to this channel in your Roku Developer Account. If this value is changed to "False" and your are using the "%NAME" macro in any of the remaining parameters, you will need to make sure that you specify a Product Name for each Purchase button.
  12. All remaining parameters on the "Roku Billing Settings" page can remain at their default values. These parameters are used to customize the on-screen receipts and messages related to In-Channel Purchases.

Additional Suggestions

  • The same Identifier can be used in the Purchase buttons and Products in multiple video items at the same time. This allows a single Purchase button to activate the same service across many videos simultaneously. This can be used, for example, to activate HD streaming across all episodes of a series by configuring the same Product Identifier and PurchaseType in each of the episodes.
  • It is not necessary to have matching Identifiers for the Purchase buttons and the Products within an individual video item. For example the Purchase button Identifier in one video item could enable access to an HD stream or ad removal in a different video item that has the same Product Identifier.
  • Instead of a Purchase button in a Springboard, a Programmable Button can be used to complete an In-Channel Purchase. A purchase made with a Programmable Button will affect any item containing a Product Identifier that matches the Identifier used in the Programmable Button, the same way that a Springboard Purchase button would.

- o -


Please see this Quick 5-Minute Guide for information about how to get started with Instant TV Channel.

Suggestions, comments, or questions about this Roku tutorial can be sent to .

Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.



Private Channel Code: ITVC
Check out Instant TV Channel by adding our demonstration channel to your Roku player, or watch the YouTube video.

Need help with your Roku?

We are unable to provide technical support for your Roku device or for channels not created using Instant TV Channel.

Please visit www.roku.com for assistance.



Instant TV Channel is not affiliated with nor endorsed by Roku Inc.