A single content item can have multiple Product blocks, allowing you to offer different types of purchases for the same video. For example, you might offer separate purchases for ad removal and HD quality upgrade.

Use Case: Separate Ad Removal and Quality Upgrade

1. In your Roku Developer Account, create two products:
   • Product 1: "Ad Removal" with SKU "AD-REMOVAL"
   • Product 2: "HD Quality" with SKU "HD-QUALITY"
2. In ITVC, edit your content item and add two Product blocks:

   Product Block 1 (Ad Removal):

   • Identifier: AD-REMOVAL (the SKU from your Roku Developer Account)
   • Purchase Type: ad removal

   Product Block 2 (Quality Upgrade):

   • Identifier: HD-QUALITY (the SKU from your Roku Developer Account)
   • Purchase Type: quality
3. Add corresponding Purchase buttons for each product:
   • Button 1: "Remove ads for $2.99" with Identifier: AD-REMOVAL (must match the SKU)
   • Button 2: "Upgrade to HD for $1.99" with Identifier: HD-QUALITY (must match the SKU)

When a viewer purchases ad removal, ads will be removed but standard quality remains. When they purchase HD quality, they get HD streams but still see ads (unless they also purchase ad removal).

Product Purchase Type Interaction Matrix

When multiple Product blocks with different Purchase Types are configured for a single content item, they interact according to the matrix below. The availability of one product can affect the services provided by another product.

For example, if the "content" purchase type is offered by itself, the viewer has both HD and SD streams available after purchasing. But if the "quality content" purchase type is also offered, then the "content" purchase type only provides SD stream, and the viewer must purchase the "quality content" product to access HD streams.

You can use the same SKU (Identifier) across multiple content items. When a viewer purchases the product once, they gain access to all content items that share that Identifier.

Use Case: Subscription Unlocks Multiple Videos

Scenario: You have 10 videos in your channel. You want viewers to purchase a single monthly subscription that unlocks all 10 videos.

1. In your Roku Developer Account, create one product:
   • Product Name: "Monthly Subscription"
   • SKU: MONTHLY-SUB
   • Purchase Type: Monthly Subscription
2. In ITVC, add the same Product block to all 10 videos:
   • Identifier: MONTHLY-SUB (the SKU from your Roku Developer Account)
   • Purchase Type: content
3. Add a Purchase button to each video:
   • Label: "Subscribe for $9.99/month"
   • Identifier: MONTHLY-SUB (must match the SKU)
   • Button Display: "hide if this product is purchased"

When a viewer purchases the subscription from any video, all 10 videos become unlocked immediately. The Purchase buttons will be hidden on all videos because the product has been purchased.

Instead of adding Product blocks to every content item individually, you can configure global product identifiers that apply to all content in your channel. This is useful for channels where one or two subscriptions unlock all content.

ITVC provides two global product slots. Each slot consists of:

• Product Identifier (SKU) - The SKU from your Roku Developer Account
• Purchase Type - What the product does (content, ad removal, quality, etc.)

Configuring Global Product Identifiers

1. In ITVC, navigate to the Roku Billing Settings page (click "Roku Billing" in the left sidebar).
2. Locate the In-Channel Purchase Settings section.
3. Configure the global product slots:

   Slot 1:

   • All Items Product ID 1 - Enter your first SKU (e.g., "MONTHLY-SUB")
   • All Items Purchase Type 1 - Select purchase type (e.g., "content")

   Slot 2 (optional):

   • All Items Product ID 2 - Enter your second SKU (e.g., "AD-REMOVAL")
   • All Items Purchase Type 2 - Select purchase type (e.g., "ad removal")

Example: Channel-Wide Subscription

If you set All Items Product ID 1 to "CHANNEL-SUB" and All Items Purchase Type 1 to "content", then all videos in your channel will require that purchase to play. You do not need to add individual Product blocks to each video.

Example: Subscription + Ad Removal

You can use both slots for different purposes:

• Slot 1: All Items Product ID 1 = "PREMIUM-SUB", All Items Purchase Type 1 = "content"
• Slot 2: All Items Product ID 2 = "AD-FREE", All Items Purchase Type 2 = "ad removal"

With this configuration, viewers must purchase "PREMIUM-SUB" to play any video, and can optionally purchase "AD-FREE" to remove ads from all videos.

Excluding Individual Videos from Global Settings

You can exclude specific videos from the global product identifiers, allowing those videos to be streamed for free while the rest of your channel remains behind a paywall.

1. Edit the content item that you want to make available for free.
2. Locate the IgnoreInChannelPurchase parameter.
3. Set IgnoreInChannelPurchase to "True".

This video will now play without requiring any purchase, even though global product identifiers are configured. This is useful for:

• Free preview or sample content to attract subscribers
• Promotional videos or trailers
• Introduction or "how to subscribe" videos

Product identifier macros allow you to define a Product Identifier (SKU) in one location and use it throughout your channel. This uses Control items with "text macro" type to perform find-and-replace on text parameters.

How Text Macros Work

A text macro consists of a placeholder string followed by a colon, followed by the replacement value. When your channel runs on a Roku device, all instances of the placeholder are replaced with the value.

Example macro: $PID$:MONTHLY-SUB

This macro replaces all instances of "$PID$" with "MONTHLY-SUB" in text parameters throughout your channel.

Setting Up a Product Identifier Macro

1. Add a Control item to the top level of your content tree by right-clicking on the top-level folder and selecting "New Control".
2. Change the Control item's ControlType to "text macro".
3. In the ControlParagraph field, enter your macro:

   $PID$:MONTHLY-SUB

   (You can use any placeholder text you want, such as $PRODID$, %%SKU%%, etc.)

4. In your content items, use the placeholder "$PID$" wherever you would normally enter the Product Identifier (SKU). For example:
   • Product block Identifier: $PID$
   • Purchase button Identifier: $PID$
   • Condition parameter: purchased=$PID$

Example: Channel with Single Subscription

You have a channel with 50 videos that all use the same subscription SKU "PREMIUM-ACCESS". You need to enter this Identifier 100+ times (once in each Product block and Purchase button for each video).

During development and testing, you may need to change the SKU multiple times (e.g., from "PREMIUM-ACCESS" to "PREMIUM-2025" to "PREMIUM-TEST"). Without macros, each SKU change requires 100+ individual edits. With macros, you only change one definition.

Setup: Create one text macro Control item at the top level:

Macro: $PREMIUM$:PREMIUM-ACCESS

Then in all 50 videos, use "$PREMIUM$" as the Identifier (100+ entries). This requires the same initial effort, but when you need to change the SKU from "PREMIUM-ACCESS" to "PREMIUM-2025", you only update the macro definition in one place instead of editing 100+ individual entries.

Benefit: Macros save editing time when SKUs change, not during initial data entry. This is especially valuable during testing when Product Identifiers change frequently.

In addition to Springboard Purchase buttons, Programmable Buttons can be used to initiate In-Channel Purchases. Programmable Buttons are grid-style buttons that can be placed in lists alongside videos.

When to Use Programmable Buttons for Purchases

• Auto-play lists where viewers never see a Springboard screen
• Channels with a free preview loop followed by premium content
• Purchase prompts within scrolling content grids
• Channel layouts that don't use Springboard screens

Configuring a Programmable Button for Purchase

1. Create a new Programmable Button item in your content tree by right-clicking on a list and selecting "New Programmable Button".
2. Set the Function parameter to "in-channel purchase".
3. Set the Identifier parameter to the Product SKU (e.g., "MONTHLY-SUB"). Text macros work here (e.g., "$PID$").
4. Set the Purchase Success parameter to "restart channel". This ensures the channel reloads after purchase to recognize the new purchase state.
5. Provide custom artwork via the ChannelSetupUrl parameter that describes what the viewer will be purchasing. This image is displayed as the button's poster.

The DoNotDisplay and Condition parameters can be used together to show or hide content based on purchase status. This allows you to create channels with free preview content and premium paid content that only appears after purchase.

How Conditional Display Works

Each content item and list has a DoNotDisplay parameter with three settings:

• no - Item is always displayed (default)
• yes - Item is always hidden
• yes if condition is true - Item visibility depends on the Condition parameter

The Condition parameter supports testing whether a Product Identifier (SKU) has been purchased using the syntax:

purchased = PRODUCT-SKU

Example: Hide Free Content After Purchase

You have a "Free Preview" list that should be hidden after the viewer purchases the "PREMIUM-SUB" product.

1. Edit the "Free Preview" list item
2. Set DoNotDisplay to "yes if condition is true"
3. Set Condition to: purchased=PREMIUM-SUB

The Free Preview list will be hidden (not displayed) when the product has been purchased.

Example: Show Premium Content Only After Purchase

You have a "Premium Content" list that should only appear after the viewer purchases the "PREMIUM-SUB" product.

1. Edit the "Premium Content" list item
2. Set DoNotDisplay to "yes if condition is true"
3. Set Condition to: !purchased=PREMIUM-SUB

The exclamation point (!) negates the condition, so the list will be hidden when the product has NOT been purchased, which is the same as saying it will be displayed when the product HAS been purchased.

Example: Using Text Macros in Conditions

Text macros work in the Condition parameter. If you have a macro $PID$:PREMIUM-SUB, you can use:

• Condition: purchased=$PID$
• Condition: !purchased=$PID$

For more conditional display options (date/time, country code, device type, etc.), see the DoNotDisplay Condition Cookbook.

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 address, first name, and last name) with each purchase, the user data will be stored in the bucket as part of the purchase's transaction file. The ITVC "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.

Setup Instructions

1. Click on the "Roku Billing" link on the left side of the Instant TV Channel page.
2. Copy and paste the 36-character "API Key" from the "Roku Pay Web Services" 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 bucket Region must be set to "US East (N. Virginia)".
   • 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.
5. Click the Policies link on the left side of the page.
6. Click the Create policy button near the top of the page.
7. Click the JSON tab, and erase the sample lines of JSON text.
8. Copy the security policy below and paste it into the JSON text box. Replace the two instances of

   my-transaction-bucket

   in the policy with the name of the bucket that you just created. This JSON security policy code allows files in the Transaction bucket to be both read from and written to.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:*"
         ],
         "Resource": [
           "arn:aws:s3:::my-transaction-bucket",
           "arn:aws:s3:::my-transaction-bucket/*"
         ]
       }
     ]
   }

9. Click the Next: Tags button near the bottom of the page.
10. Click the Next: Review button near the bottom of the page.
11. Provide a new Policy Name, for example "my-transaction-policy". You may optionally also enter a Policy Description.
12. Click the Create policy button near the bottom of the page.
13. Click the User groups link on the left side of the page.
14. Click the Create group button near the top of the page.
15. Provide a new User group name, for example "my-transaction-group".
16. Scroll down to the list of policies, and locate the "my-transaction-policy" policy that you just created, or type the name of your newly created policy in the "Filter" box. You may need to scroll through a large number of built-in AWS policies until your policy is visible.
17. Check the checkbox to the left of your policy name, making sure that no other checkboxes are checked, then click the Create Group button near the bottom of the page.
18. Click the Users link on the left side of the page.
19. Click the Add Users button near the top of the page.
20. Provide a new User name, for example "my-transaction-user".
21. Click the Next button near the bottom of the page.
22. Check the checkbox to the left of the previously created Group name, then click the Next button near the bottom of the page.
23. Click the Create user button near the bottom of the page.
24. Click the previously created User name from the list of users. This will display a Summary page for the user.
25. Click the Security credentials link or tab.
26. Click either of the Create access key buttons.
27. Select Other, then click the Next button.
28. Click the Create access key button.
29. Click the Show link beneath "Secret access key" or click the Download .csv button to copy and save the Access Key ID and Secret Access Key. These keys will be used exclusively for access to your Transaction bucket. They cannot be used to access any other AWS buckets or services. 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.

30. After copying the Security Credentials, click the Close button near the bottom of the page.

    At this point we have a new IAM user that is a member of a new IAM group - the user has the keys and the group has the security policy. This will allow the keys to be used in the Roku channel to access the S3 bucket specified by the security policy.

31. Enter the name of the Transaction bucket that you just created into the Instant TV Channel Transaction Bucket Name parameter on the Instant TV Channel "Roku Billing" page.
32. 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.
33. Enter the Access Key ID that you just created into the Instant TV Channel Transaction Bucket Access Key ID parameter.
34. Enter the Secret Access Key that you just created into the Instant TV Channel Transaction Bucket Secret Access Key parameter.
35. 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.

During an In-Channel Purchase, Roku can prompt viewers to share their email address, first name, and last name. If the viewer agrees, this data is stored in the S3 transaction receipt file.

User Data Parameter Settings

The User Data parameter on the ITVC "Roku Billing" page controls how user data is collected:

Privacy Considerations

• Use "request" (default) to respect viewer privacy while offering the option to share
• Use "none" if you don't need user contact information
• Avoid "require" unless absolutely necessary, as it creates friction in the purchase flow

The ITVC "Roku Billing" page provides numerous parameters for customizing on-screen messages and receipts displayed during and after purchases. These parameters allow you to tailor the purchase experience to match your channel's branding and terminology.

Success Messages

After a successful purchase, Roku displays a confirmation screen. You can customize the messages using:

• Success Top - The heading message (e.g., "Thank you for your purchase!")
• Success Bottom - The detail message (e.g., "You now have access to premium content.")

These messages should accurately reflect what the viewer purchased (subscription vs. one-time purchase, monthly vs. annual, etc.).

Product Name Macro

The %NAME macro can be inserted into message parameters to display the Product Name dynamically. The Product Name comes from either the Purchase button configuration or the Roku Developer Account product catalog.

Example: Success Top = "Thank you for purchasing %NAME"

Use Store Catalog Setting

The Use Store Catalog parameter determines where Product Names come from:

• True (default) - Product Names are loaded from the Roku Catalog 2.0 API using your Roku API Key. This is recommended for most channels.
• False - Product Names must be specified in each Purchase button's Product Name parameter. Only needed for channels with a very large number of products.

Additional Customizable Parameters

The "Roku Billing" page includes additional parameters for customizing:

• Error messages when purchases fail
• Messages when products are already purchased
• Receipt formatting and display
• Purchase confirmation dialogs

Most parameters have sensible defaults and do not require changes unless you want specific custom messaging for your channel.

This example demonstrates an advanced Roku Pay implementation using text macros, conditional display, and programmable buttons. The channel has two auto-play loops: a free preview loop and a premium paid loop.

Channel Structure

• Control item (text macro) - Defines $PID$:MY_PRODUCT_ID macro for the subscription SKU
• List of All Items - Container list with AutomaticPlay="once" to automatically enter one of the two loops
• Loop of Free Videos - Auto-play loop with preview content, hidden after purchase (DoNotDisplay="yes if condition is true", Condition="purchased=$PID$")
• Programmable Button - Purchase button within Free loop (Function="in-channel purchase", Identifier="$PID$", PurchaseSuccess="restart channel")
• Loop of Premium Videos - Auto-play loop with paid content, shown only after purchase (DoNotDisplay="yes if condition is true", Condition="!purchased=$PID$")

How It Works

1. Channel starts automatically (top-level AutomaticPlay="once")
2. Macro substitution runs at startup, replacing all $PID$ references with MY_PRODUCT_ID throughout the channel
3. If no purchase has been made:
   • Free loop is visible (purchased=$PID$ is false, so DoNotDisplay condition is false)
   • Premium loop is hidden (!purchased=$PID$ is false, so DoNotDisplay condition is true)
   • Free videos play in a loop
   • Programmable Button appears in the loop, offering the upgrade purchase
4. If purchase is made:
   • Channel restarts (PurchaseSuccess="restart channel")
   • Free loop is hidden (purchased=$PID$ is true, so DoNotDisplay condition is true)
   • Premium loop is visible (!purchased=$PID$ is true, so DoNotDisplay condition is false)
   • Premium videos play in a loop

Key Implementation Details

• Control macro at top level: Allows the Product ID to be configured in one location instead of three places (Free loop condition, Premium loop condition, Programmable Button identifier)
• Nesting requirement: All items using the macro must be nested below the Control item for consistent macro substitution. The "List of All Items" serves this purpose.
• Restart after purchase: Necessary because conditional display (DoNotDisplay/Condition) is only evaluated when the channel starts. The PurchaseSuccess="restart channel" setting triggers this restart.
• Custom artwork: The Programmable Button requires custom artwork (via ChannelSetupUrl parameter) to describe what the viewer is purchasing.

Import This Example

You can import this example channel into your ITVC account using Channel ID: 1f71f178-64a5-45d7-bbd1-e330b9e57a8a

Content tree for the example channel