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 user 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 user entitlement query, purchase request, and cancel request to your skill code.

Determine user 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 user entitlement status. The Customer entitlement query returns an entitled status set to ENTITLED to indicate that the user 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 user 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 user 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 user 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. For details, see Test Your Skill. Complete the following paid-skill test scenarios before you submit your skill for certification. In addition, complete testing requirements for certification. For details, see Certification Requirements.

After you complete testing, you have the option to test your skill with a limited group of testers, rather than publish the skill to the general public. For details, see Beta Test a Skill.

Test the purchase flows

In the development stage, Amazon doesn't charge the developer account associated with the skill. During testing, you can reset the status of a purchase by using the reset-isp-entitlement command.

Include the following test scenarios:

  • Entitlement query with various responses
  • Purchase flows for your payment model, including direct purchase and after purchase suggestion
  • Customer declines the purchase
  • Customer cancels a subscription
  • Customer asks to cancel a subscription, but then continues the subscription
  • Customer asks for a refund

Test in different marketplaces

If your skill supports multiple marketplaces, you can use the Alexa Simulator to test purchasing in the default locale for each marketplace. With the simulator, you can test each marketplace by using your developer account. If you want to test on a physical Echo device, you must create an account in each marketplace.

To test purchasing for each marketplace

  1. Sign in to the Alexa developer console.
  2. Find your skill in the list.
  3. Under Actions, choose Edit.
  4. On the Test page, for Test is disabled for this skill, select Development.
  5. Under Alexa Simulator, select the locale for which you want to test purchasing.

    A screenshot of the Alexa developer console that shows the drop-down to select locale.
  6. Use voice or text to launch your skill, and then interact with your skill appropriately.
    Based on the locale that you selected, the Alexa Simulator uses the price that corresponds to the default locale for the region in the purchasing flow.

Test the user experience

Make sure that your skill passes the user experience tests for a custom skill. Then, complete the following tests.

Test Expected result

Open your skill to invoke the purchase scenario for your skill.

The purchase suggestion makes sense. A user knows what the skill has asked them to purchase. The purchase prompt doesn't include the list price. The purchase suggestion and purchase prompt are different.

Directly invoke the purchase scenario for your skill.

The purchase suggestion makes sense. A user knows what the skill has asked them to purchase. The purchase prompt doesn't include the list price. The purchase suggestion and purchase prompt are different.

Open your skill, complete a successful purchase, and then end the skill session. Resume the skill session, and then try to use the skill.

Your skill handles the user entitlement check correctly and that the user can use the skill in another session. Make sure that the user doesn't receive a purchase suggestion for a skill they already own.

Buy your skill.

Review the purchase receipt for each item. The description and image for the product accurately reflect the product purchased.

Attempt to buy a skill with invalid payment information.

The user hears the failure reason during the purchase flow. Your skill doesn't repeat the information, but resumes free content or ends the skill session.

Complete a purchase scenario with decline.

The user accepts the purchase suggestion, but declines the offer. Make sure that the user doesn't receive a purchase suggestion after the skill resumes.

For subscription payment models, cancel the subscription with a voice request.

The user can cancel the subscription successfully. The user can access the skill until the end of the current subscription period. The user can't access the skill after the subscription period ends.

For one-time purchase models, ask for a refund.

The user can ask for a refund, and then the skill session ends. The user sees a link in the Alexa app to Amazon customer support.

Test your live skill

The developer account associated with a skill never incurs the cost of the purchases during development. To test the user experience fully, complete a final test with an account other than your developer account. Amazon charges for all purchases during live skill testing.

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.