Steps to Build a Paid Skill
You can create a new custom skill and define it as a paid skill. You add purchase flows to your skill logic to transfer control to Alexa to guide the customer through the purchase.
Complete the following steps to build a paid skill. For an overview of paid skills, see Understand Paid Skills.
Prerequisites
To build a paid skill, you must comply with the following prerequisites:
- You can designate a skill as a paid skill when you choose the custom voice interaction model and create the skill in a language that supports paid skills.
For more details, see Understand Custom Skills and Create the Interaction Model for Your Skill. - You can offer paid skills in the following languages: English (US), Spanish (US).
Workflow: Build a paid skill
Complete the following steps to build a paid skill.
- Configure purchase details
- Design purchase and cancel flows
- Add purchase and cancel intents to your interaction model
- Add the purchase and cancel requests in your skill code
- Test your skill
- Provide publishing information
- Submit your skill for certification
Step 1: Configure purchase details
You can offer your paid skill as a one-time payment or as a subscription. You configure the payment model and purchase details by using the Alexa developer console. For details, see Define Purchase Details.
Step 2: Design purchase and cancel flows
When you offer your skill as a paid skill, you design the purchase suggestion and the transfer to Alexa to complete the purchase. You also design cancellation and refund flows. For details, see Design the Purchase and Cancel Flows.
Step 3: Add purchase and cancel intents to your interaction model
Next, add custom intents to your interaction model for the direct purchase and cancellation flows. These intents support the cases when a customer asks Alexa to buy, cancel, or refund your skill directly. For more details, see Create Intents, Utterances, and Slots.
The following example shows buy and cancel intents for a Quick Trivia paid skill with a subscription payment model.
{
"interactionModel": {
"languageModel": {
"invocationName": "quick trivia",
"intents": [{
"name": "AMAZON.CancelIntent",
"samples": []
},
{
"name": "AMAZON.HelpIntent",
"samples": []
},
{
"name": "AMAZON.StopIntent",
"samples": []
},
{
"name": "AMAZON.NavigateHomeIntent",
"samples": []
},
{
"name": "AMAZON.FallbackIntent",
"samples": []
},
{
"name": "BuyIntent",
"slots": [],
"samples": [
"buy quick trivia",
"purchase quick trivia",
"want quick trivia",
"would like quick trivia"
]
},
{
"name": "CancelSubscriptionIntent",
"slots": [],
"samples": [
"cancel subscription to quick trivia",
"stop subscription to quick trivia",
"don't want quick trivia",
"refund quick trivia"
]
}
]
}
}
}
Step 4: Add the purchase and cancel requests in your skill code
In this step, you add the customer entitlement query, and purchase and cancel requests to your skill code.
Determine customer entitlement
At the start of each skill session, to determine whether to invoke the purchase flow or to continue with paid skill content, get the customer entitlement status. The Get customer entitlement API returns ENTITLED
to indicate that the customer purchased the skill, or a free trial is in progress. If the customer hasn't purchased the skill, the free trial expired, or the customer canceled the subscription, the interface returns NOT_ENTITLED
.
Invoke the purchase flow
Your skill transfers the skill session to the Amazon purchase flow in the following cases:
- When the entitlement query indicates that the customer hasn't purchased your skill and you don't have free content to provide.
- When the customer asks Alexa to purchase your skill by voice and your skill receives a buy intent.
To invoke the purchase flow, include the Buy
request in your response to Alexa from an intent handler. Your skill session ends when the purchase flow starts. Amazon handles the voice interaction model and all the mechanics of the purchase.
Your skill session ends when you send the buy request. Make sure that you save any relevant customer data in a persistent data store, such as AWS DynamoDB or S3. You can use any persistent storage that you want.
After the purchase flow completes, Alexa launches your skill again. Add code to continue with the skill seamlessly, based on the purchaseResult
. For details, see Purchase and Cancel response.
Handle cancellations and refunds
When the customer asks Alexa to cancel their subscription to your skill or requests a refund, your skill receives the cancel intent. Like the purchase flow, your skill transfers cancellation and refund requests to Alexa. To cancel and provide a refund, include the Cancel
request in your response to Alexa.
Your skill session ends when you send the cancel request. Make sure that you save any relevant customer data in a persistent data store.
After the cancellation flow completes, Alexa launches your skill again. Add code to continue or end the skill, based on the purchaseResult
. For details, see Buy and cancel response.
Step 5: Test your skill
When you're ready to test your skill, you can use the Alexa simulator in the Alexa developer console to test skill functionality and the purchase and cancellation flows. For details, see Test Paid Skills.
Step 6: Provide publishing information
To distribute your skill to the Amazon Alexa Skills Store, you must fill out the required metadata for your skill on the Distribution tab in the developer console. Make sure that you provide links to a privacy policy and terms of use page and that all tappable and clickable links open and display properly on iOS , Android and desktop devices. Your skill must have an associated icon, and icon URL that resolves correctly.
After you complete and save the skill information, you can distribute your skill for beta testing or submit it for certification.
Step 7: Submit your skill for certification
Before you submit your skill for certification, make sure that your skill passes all certification testing requirements and meets the certification requirements. You must also complete the tax identity interview and enter payment information.
To submit your skill for certification, see Submit Skills for Certification in the Alexa Developer Console.
Sample code
The following sample code demonstrates how to use the purchase flow in a paid skill:
Related topics
- Paid Skills Interface Reference
- Paid Skill Schemas
- ASK SDK for Node.js Monetization Service Client
- ASK SDK for Python Monetization Service Client
Last updated: May 01, 2024