Steps to Implement Paid Skills

You can create a new custom skill and define it as a paid skill. You add purchase flows to your skill logic to the handoff to Alexa to guide the customer through the purchase.

Complete the following steps to implement a paid skill. For an overview of paid skills, see Understand Paid Skills.

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 details about custom skills, see Understand Custom Skills.

You can offer paid skills in the following languages: English (US), Spanish (US).

Design purchase and cancel flows

When you offer your skill as a paid skill, you design the purchase suggestion and the handoff to Alexa to complete the purchase. You also design cancellation and refund flows. For details, see Design the Purchase and Cancel Flows.

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.

Add purchase and cancel intents

After you design the purchase and cancellation flows, add custom intents. Adding the intents supports the cases when a customer asks Alexa to buy, cancel, or refund your skill directly.

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"
                    ]
                }
            ]

        }
    }
}

Add the purchase and cancel requests in your skill code

In this step, you add the customer entitlement query, purchase request, and cancel request 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 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 hands off 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 hand off to 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 hands off 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.

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. In addition, complete testing requirements for certification. For details, see Certification Requirements.

Submit your skill for certification

After you complete testing, define skill details and availability. Your skill must have an associated icon, and icon URL that resolves correctly.

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.

Submit your skill for certification. For details, see Test and Submit Your Skill for Certification.

Receive payment

After you receive certification and publish your Alexa paid skill, you're ready to earn royalties. For details about receiving payments, see Get Paid.

View skill metrics and earnings

You can monitor the performance of your skill in the developer console. Use the Analytics page in the developer console to view skill metrics and generate reports. For details about the available metrics, see About Skill Metrics.

Use the Earnings and Payments tab in the developer console to view sales reporting and analytics that include information about purchases, conversions, retentions, refunds, cancellations, and more. For more details, see View Your Earnings and Payments

Sample code

The following sample code demonstrates how to use the purchase flow in a paid skill:

Was this page helpful?

Last updated: Jun 28, 2023