Alexa Blogs
Now with the availability of in-skill purchasing (ISP), we’re excited to see what kinds of premium experiences you will offer customers. We shared some tips on how to design a great customer experience when building in-skill purchases. Here we’ll walk you through how to use the Alexa Skills Kit Command-Line Interface (or ASK CLI) to start building skills that include one-time purchases and subscriptions. If you haven’t used the ASK CLI before, check out the ASK CLI Quick Start Guide.
Adding In-Skill Purchases to Your Alexa Skill
Before you can start selling products and subscriptions in your skill, you first need to create them. To do this, we will use the ASK CLI. (For a list of all of the CLI commands for in-skill purchases, click here.) When you use the command:
ask add isp
You will be presented with a choice of product types to create.
- Entitlements: One-time purchase to unlock access to features or content within a skill
- Subscriptions: Access to a premium set of content or features for a limited period of time
An in-skill product is a JSON file that is added to your skill’s project folder. You can see examples of these JSON files in our technical documentation, as Entitlement Template or Subscription Template.
Once these new in-skill products have been created, you still need to deploy them to your skill. To do this, you can use the standard “ask deploy” command, or to deploy only the ISPs, you can use:
ask deploy --target isp
At this point, your skills have been deployed and are available to access in your code. They will not be available to your customers until you submit your skill through certification, however.
Listing Your Available Products
Once your products have been deployed, you can use the new In-Skill Purchase API to retrieve the list of your available products their purchase status with the current customer. For example, if the current customer has already purchased the Science Trivia Pack, that product will be marked as “ENTITLED,” because they have already paid for it. Items they haven’t purchased are marked as “NOT_ENTITLED.” (You can read more in our technical documentation, Adding ISPs to a Skill.) You can see the full set of properties in the following JSON snippet:
{
"productId": "amzn1.adg.product.some-id",
"referenceName": "ProductName",
"type": "SUBSCRIPTION",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "NOT_ENTITLED",
"purchasable": "PURCHASABLE"
}
At the beginning of each session, make a call to this API to retrieve your product list. This will make it easy for you to recommend products the user doesn’t yet have and honor the products they’ve already purchased.
Suggesting a Purchase to Your Customer
There will be many opportunities, when a customer is using your skill, to remind them that there are additional products available for purchase. For example, after a customer finishes playing your free daily quiz, you could mention that the skill offers additional daily quizzes on a variety of subjects as part of your monthly “all access” Quiz Subscription. The following code sample shows how you can use the ASK node.js SDK to send this command.
return handlerInput.responseBuilder
.addDirective({
'type': 'Connections.SendRequest',
'name': 'Upsell',
'payload': {
'InSkillProduct': {
'productId': product.productId
},
'upsellMessage': product.summary + ". Want to learn more?"
},
'token': 'correlationToken'
})
.getResponse();
Once this request is sent, the Alexa service takes over and handles the rest of the transaction. This includes things like reading the product description, offering the pricing, and concluding the purchase. (This is all based on the content of your ISP's JSON file, of course.) Once the transaction is completed, a new request type, Connections.Response, is sent to your skill, alerting you to the results of the interaction.
"request": {
"type": "Connections.Response",
"requestId": "amzn1.echo-api.request.5ad97da2-8581-4693-aa6f-17a21c81efb7",
"timestamp": "2018-04-24T13:29:30Z",
"locale": "en-US",
"status": {
"code": "200",
"message": "OK"
},
"name": "Buy",
"payload": {
"purchaseResult": "ACCEPTED",
"productId": "amzn1.adg.product.ec40896a-4153-469a-8896-2a2ebdca03b2"
},
"token": "correlationToken"
}
Looking at the payload.purchaseResult, you will be able to determine if the user successfully made the purchase, or decided to cancel the transaction. At this point in the flow, you should acknowledge the user’s decision, and continue your skill experience.
Enabling the Customer to Be in Control
At any time, the customer can say things like, “What can I buy,” to hear a list of available products or, “I want to buy {ProductName}” to make a purchase. If the customer gives you a valid product name, go ahead and start the purchase flow. If the customer doesn’t, you should offer a few relevant products from your catalog.
When you're setting up your custom slot, use the product name in the value, the referenceName in the ID, and be sure to add variations as synonyms, like the image below.
For example, if your product is called Castle Pack, you might also include things a customer might reasonably say like "castle" "medieval" "king and queen adventure" as synonyms. Then if you get an ER_SUCCESS_MATCH in your JSON resolutions, you can use the ID to start the purchase flow. If you get an ER_SUCCESS_NO_MATCH, you can clarify and reprompt, letting the customer know you don’t have a product that matches the name they provided.
If you offer subscriptions, you also need to include a cancelSubscriptionIntent, which allows the user to cancel their subscription with their voice.
Preparing for Certification
Just like the content of your skill, your in-skill product will also need to go through certification. In-skill products are evaluated when the skill they are associated with is submitted for certification. Before you begin adding in-skill products into your skill, you should review the in-skill purchase certification guide to make sure that your approach passes the certification test cases.
Also, make sure that you provide testing instructions to the certification team, so that they have a clear understanding of how to identify, access, and purchase your in-skill products. This will make the certification testing process much smoother.
Get Started
Check out these resources to start building in-skill purchases in your Alexa skills. You can also register for our webinar or download our guide to learn about the different ways you can make money with Alexa, best practices for creating engaging, premium experiences, and how to select the right in-skill product to meet your needs. We are excited to see what you build next!
Here are some additional resources to help you get started:
