We recently announced that you can now sell premium experiences in the form of in-skill products in your Alexa skills. Customers can buy in-skill products as one-time purchases or subscriptions to unlock premium content in your skill. Adding in-skill purchasing (ISP) is a relatively simple process, but there are many considerations before you publish your first in-skill product, including your ISP metadata.

When you create an in-skill product, you generate a JSON file that represents your product.  This file contains obvious values, like price and currency, but also several other important fields that help in the purchase process. Here we unpack each of the fields to help you make full use of your ISPs.

Let’s start by looking at an entitlement (one-time purchase) from a trivia game I’m currently building.

Entitlement Product Schema

{
  "version": "1.0",
  "type": "ENTITLEMENT",
  "referenceName": "science",
  "publishingInformation": {
    "locales": {
      "en-US": {
        "name": "Science",
        "smallIconUri": "https://s3.amazonaws.com/tko-trivia/art/ISPs/science_108.png",
        "largeIconUri": "https://s3.amazonaws.com/tko-trivia/art/ISPs/science_512.png",
        "summary": "This unlocks the science category, giving you access to over 150 different questions about physics, chemistry, biology, mathematics, and astronomy.",
        "description": "This will unlock all of the science questions in TKO Trivia.  You will be able to directly request any of the science questions in this skill.",
        "examplePhrases": [
          "Alexa, buy the science category"
        ],
        "keywords": [
          "physics", "chemistry", "biology", "mathematics", "astronomy"
        ],
        "customProductPrompts": {
            "purchasePromptDescription": "Purchasing the Science category will give you questions about physics, chemistry, biology, mathematics, and astronomy.",
            "boughtCardDescription": "You have purchased the Science category!  You can now ask TKO Trivia to \"give me a science question\" when you're ready."
        }
      }
    },
    "distributionCountries": [
      "US"
    ],
    "pricing": {
      "amazon.com": {
        "releaseDate": "2018-06-01",
        "defaultPriceListing": {
          "price": 0.99,
          "currency": "USD"
        }
      }
    },
    "taxInformation": {
      "category": "SOFTWARE"
    }
  },
  "privacyAndCompliance": {
    "locales": {
      "en-US": {
        "privacyPolicyUrl": "http://tkotrivia.com/privacy"
      }
    }
  },
  "testingInstructions": "For the upsell experience (and to use it once it has been purchased), say 'Give me a science question.'  To directly buy the product, say 'buy the science pack.'",
  "purchasableState": "PURCHASABLE"
}

Version

This value indicates what version of the ISP schema you are using. Today, the only valid value is 1.0, but as in-skill purchasing grows in the future, there could be additional schema values available.

Type

This designates what kind of product this ISP represents. The value can be ENTITLEMENT or SUBSCRIPTION. An entitlement is a one-time purchase, like unlocking new content. A subscription unlocks access to specific content for a specific period of time.

Reference Name

This is what you named your ISP when you created it. The name of this file would also be science.json, for example. This name is an excellent, reliable value to help you retrieve your products in your code. I generally use a statement similar to the code below to get a reference to a specific product:

const entitlement = result.inSkillProducts.filter(record => record.referenceName === "science");

Publishing Information

This object contains the product metadata, divided up by each locale that the product is available. In-skill purchasing is currently only available in the en-US locale.

Name

This is a value that is used by the in-skill purchase flow. It can be a maximum of 50 characters.  After a customer purchases your product, Alexa will say, “Great. You now have [NAME]” before handing the experience back to your skill to continue. It is important to remember how these values will be used when creating your products, as you want this dialog to sound natural.

In my example above, a purchase would result in a customer hearing, “Great, you now have science.” I don’t love this phrasing, and I’m considering changing my name value to “The Science Questions” because it sounds more natural.

Small Icon Uri and Large Icon Uri

The icons you create for your ISP are visible to customers in their purchase receipts and order history. These two values are required before you can even deploy your products to the server, so it’s a good idea to have these ready for each of your in-skill products. If you’re in a hurry to test your skill, you can use these sample images for small and large to get started. Just make sure to replace them before you publish your skill.

Summary

This is a quick, 160-character-or-less description of your product. Think of this like the short description for your skill, but it is for this specific ISP. The ISP process does not currently use this, but it is an excellent value to use as part of your upsell process, or for describing your products in your skill.

Description

This is your full-length description of your product. It can be up to 4,000 characters long. This is another value that is currently not used, but would be an excellent description of your product in cards or on screens. You can retrieve any of the values from this JSON file from your code at any time.

Example Phrases

Much like the example phrases we create for our skills, these example phrases will indicate to a customer how to interact with our in-skill products. You should provide samples that will get your customers directly to the product they are interested in purchasing.

Keywords

Include keywords that match the key phrases customers are likely to search when looking for your skill or a premium experience. In the future, when a customer is looking for a specific type of experience, these keywords will make their search easier. These keywords are not currently used in the purchase process, but will be important to help customers find your ISP in the future.

Purchase Prompt Description

This is another important value to the purchase process. If a customer wants to learn more about an upsell message or directly buy your ISP, the purchasePromptDescription is the first message they will hear. This description can be up to 160 characters. Alexa will speak this description before outlining the price of the product, including any discounts that Prime members might receive. Make sure not to mention the price in this description. If you want to refer to the value in your [NAME] field, you can insert the {PREMIUM_CONTENT_TITLE} placeholder in your text, and the [NAME] value will be inserted when Alexa uses this value.

Bought Card Description

This value is used as the text of a card in the customer’s Alexa App when they purchase your product. I recommend congratulating them on their purchase, while also confirming that their purchase was successful. You should also give them a simple way to use their new purchase right now. The sooner they know how to use the product, the more confident they will be in buying your future offerings as well. If you want to refer to the value in your [NAME] field, you can insert the {PREMIUM_CONTENT_TITLE} placeholder in your text, and the [NAME] value will be inserted when Alexa uses this value.

Release Date

If you want to release your product on a specific future date, the release date field will allow you to indicate a future UTC date. Your product won’t be available for purchase until this date/time has passed. This value can’t be updated once you publish your ISP, so make sure you’re certain about this value before you push your skill through certification.

Price

This is the full list price (in the currency listed below) that a customer will be charged when they buy your product. You will receive 70% of this value each time you sell an ISP. Alexa may offer a 20% discount to Prime members, but this discount is taken from the remaining 30%, and not from your percentage.

Currency

This is the native currency for your product in the designated locale. The only current value available is USD, for United States Dollars.

Tax Information / Category

Because different products can be taxed at different rates, you need to categorize your product for the most appropriate tax category.  The available values are: INFORMATION, SERVICES, NEWSPAPERS, PERIODICALS, SOFTWARE, STREAMING_RADIO, and VIDEO.  If you aren’t sure which category to use, you should select SOFTWARE as your value.

Privacy Policy URL

This needs to be a link to your skill’s privacy policy.  You can have a different policy for each locale, but this must point to a working web page that indicates how your skill handles privacy information.

Testing Instructions

In the same way that we can provide testing instructions for the certification team for our entire skill, these testing instructions provide quick access to those testers trying to validate your ISP process. I recommend indicating the sample phrases that should be used to encounter both an upsell and a buy process, as these are different experiences for the customer.

Purchasable State

This is a flag that allows you to remove or add a product from your catalog of available products. If you deploy your product with this value set to PURCHASABLE, it will be available for purchase by your customers. If it is set to NOT_PURCHASABLE, it would not be possible to buy this product at this time. It should be noted that if someone has purchased this product in the past, setting this value to NOT_PURCHASABLE will not affect their experience. For example, this value makes sense if you only want to sell a product for a specific month. After the month ends, you set your product to NOT_PURCHASABLE, so that it is no longer available for sale.  Those customers that bought your product, however, will still have access to their purchase.

Subscription Product Schema

A subscription has all of the same fields that an entitlement has, but there are two additional required values: Subscription Payment Frequency and Subscription Trial Period Days.

"version": "1.0",
  "type": "SUBSCRIPTION",
  "referenceName": "all_access_subscription",
  "subscriptionInformation": {
    "subscriptionPaymentFrequency": "MONTHLY",
    "subscriptionTrialPeriodDays": 2
  }

Subscription Payment Frequency

You can offer a subscription that renews MONTHLY or YEARLY. For most products, I think it makes sense to offer a monthly subscription, but for things that don’t occur all year, like baseball statistics, it might make more sense to offer a YEARLY subscription so that a customer doesn’t feel like they’re paying for something even during the offseason.

Subscription Trial Period Days

With subscriptions, you have the ability to offer a trial period from 1 to 31 days. A trial allows a customer to try your content before they actually start paying for the subscription. After the number of days you indicate, your customer will automatically be charged for the indicated period, and will have access to your content until the end of that subscription period, even if they cancel.

If they cancel their subscription before the trial period ends, they won’t be charged for that access. However, if they try to start a subscription a second time, the trial period will not be offered. It is a great way to give your customer a taste of what they will be getting before they commit to the purchase.

In addition to reviewing each of these values carefully, make sure to review the In-Skill Purchase Certification Guide for specific tests you should review before submitting your skill for certification.

Have you started building an in-skill product? I’d love to know what you’re working on, and what kinds of questions you have along the way. Reach out to me on Twitter at @jeffblankenburg to get in touch.

Resources to Add In-Skill Purchasing

• Understanding the In-Skill Purchasing Experience
• How to Build an Alexa Skill with In-Skill Purchasing
• New Alexa Skill Sample: Add In-Skill Products with One-Time Purchases and Subscriptions
• 8 Best Practices for Designing Premium Experiences for Alexa Skills