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:

Workflow: Build a paid skill

Complete the following steps to build a paid skill.

  1. Configure purchase details
  2. Design purchase and cancel flows
  3. Add purchase and cancel intents to your interaction model
  4. Add the purchase and cancel requests in your skill code
  5. Test your skill
  6. Provide publishing information
  7. 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. 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:


Was this page helpful?

Last updated: Jan 26, 2024