When we released in-skill purchasing (ISP), I was excited to start building premium content that customers would be able to purchase with just a voice conversation. In the time I’ve spent building skills with ISP, I’ve been able to identify the common pathways a customer can travel during the purchase process. It starts with two core ideas:

• You recommend a product to your customer, which we call an upsell.
• Your customer asks to purchase a product, which we call a buy.

If a customer likes your upsell, they proceed to a buy offer. If they accept the offer or decline at any point, Alexa returns to your skill with a response and purchase result that reflects their choice.

In this post, we are going to cover each of the possible pathways a customer can take to make (or decline) a purchase in an Alexa skill and share some best practices to create a seamless in-skill purchasing experience.

Offering Your Customer an Upsell

An upsell is something you present to your customer when you identify an opportunity to sell them one of your in-skill products. Examples of this might be offering another story in your storybook skill, or more questions from your trivia skill.

To trigger an upsell to the customer, send the following JSON as your response to Alexa:

{
type: “Connections.SendRequest”,
name: “Upsell”,
payload: {
	InSkillProduct: { productId: “YOUR_PRODUCT_ID” },
           	upsellMessage: “YOUR_UPSELL_MESSAGE”
},
    	token: 'correlationToken',
}

If the customer declines your upsell offer, you will receive new JSON data of type “Connections.Response”.  You should return your customer back to your skill’s free experience when you receive this message in your skill.

"request": {

        "type": "Connections.Response",

        "requestId": "amzn1.echo-api...",

        "timestamp": "2018-06-20T00:51:42Z",

        "locale": "en-US",

        "status": {

            "code": "200",

            "message": "OK"

        },

        "name": "Upsell",

        "payload": {

            "purchaseResult": "DECLINED",

            "productId": "amzn1.adg...",

            "message": "Skill Upsell was declined."

        },

        "token": "correlationToken"

    }

Here’s an example of what the conversation might look like in a trivia skill:

Customer: Give me a science question.

Alexa: You don’t currently have access to the science category. Would you like to hear how to get it?

Customer: No, thank you.

Alexa: OK.  Can I offer you one of our free trivia questions instead?

As you can see, when the customer declines the offer, you can handle this gracefully and move the customer back to the experience they were enjoying before the upsell.

If the customer wants more information about the product that you offered an upsell on, they will automatically be moved into a buy experience. This is the part of the purchase process where Alexa will inform the customer about what they are purchasing, and how much it costs.  Here’s what it looks like:

Customer: Give me a science question.

Alexa: You don’t currently have access to the science category. Would you like to hear how to get it?

Customer: Yes, please.

Alexa: Purchasing the science category will give you questions about physics, biology, chemistry, and astronomy. Prime members save 19 cents, without Prime the price is 99 cents plus tax. Would you like to buy it?”

If they decline this offer, you will receive the same “DECLINED” message that we saw above. If they accept the offer and BUY your product, you will receive a similar response, but the purchaseResult value will be “ACCEPTED.”

"request": {

        "type": "Connections.Response",

        "requestId": "amzn1.echo-api...",

        "timestamp": "2018-06-20T00:51:42Z",

        "locale": "en-US",

        "status": {

            "code": "200",

            "message": "OK"

        },

        "name": "Upsell",

        "payload": {

            "purchaseResult": "ACCEPTED",

            "productId": "amzn1.adg...",

            "message": "Skill Upsell was accepted."

        },

        "token": "correlationToken"

    }

At this point, you should thank the customer for their purchase, and immediately take them to an experience that uses their purchase.

…

Alexa: Would you like to buy it?

Customer: Yes!

Alexa: Great. You have successfully unlocked the Science category. You can now say things like ‘Ask me a science question.’ Would you like a science question now?

Making It Easy for a Customer to Buy Directly

Many times, a customer won’t buy something the first time they hear about it. As they are using your skill, however, it may occur to them that purchasing a specific product would be worthwhile. In this case, you should be prepared for them to ask to purchase a product by name. To do this, I recommend building a BuyIntent in your interaction model that has a slot value for each of the products you have to offer. Here’s an example:

{
    "name": "BuyCategoryIntent",
    "slots": [
        {
            "name": "category",
            "type": "Category"
        }
    ],
    "samples": [
        "I want to buy the {category} category",
        "purchase {category}",
        "buy {category}",
        "I want to unlock {category}",
        "unlock {category}"
    ]
}

Once the customer has indicated that they want to buy a product, you can skip past the upsell experience, and take them directly to a buy offer. To do this, we use a slightly different “Connections.SendRequest” JSON request (shown below). Notice that this one does not include an UpsellMessage, as the buy experience is a pre-set script that uses your purchasePromptDescription from your ISP, followed by the specific pricing offer for your customer.

{
    'type': 'Connections.SendRequest',
    'name': 'Buy',
    'payload': {
                'InSkillProduct': {
                    'productId': “YOUR_PRODUCT_ID”
                }
    },
    'token': 'correlationToken'
}

Once you submit your buy request, the experience is identical to the experience we saw when a user accepted our upsell.

Customer: Buy the science category.

Alexa: Purchasing the Science category will give you questions about physics, biology, chemistry, and astronomy. Prime members save 19 cents, without Prime the price is 99 cents plus tax. Would you like to buy it?”

If the customer decides not to purchase your product, your skill should function identically to the Upsell Declined exerience we discussed earlier. Return the customer to their current experience, and move past a purchase conversation. 

"request": {

        "type": "Connections.Response",

        "requestId": "amzn1.echo-api.request.05d4c3bf-d913-4241-ab64-47e65326ef7d",

        "timestamp": "2018-06-20T01:43:37Z",

        "locale": "en-US",

        "status": {

            "code": "200",

            "message": "OK"

        },

        "name": "Buy",

        "payload": {

            "purchaseResult": "DECLINED",

            "productId": "amzn1.adg.product.034a3d20-026a-4c86-9879-815f57266ddb"

        },

        "token": "correlationToken"

}

Because the customer initiated this purchase conversation, I like to remind them that they can buy these products at any time by just asking for them.

…

Alexa: Would you like to buy it?

Customer: Nope.

Alexa: OK. You can always buy any of our trivia categories by simply asking for them.  What would you like to do instead?

If the customer decides to make the purchase, the “purchaseResult” becomes ACCEPTED, but all of the other values remain unchanged.

"request": {

        "type": "Connections.Response",

        "requestId": "amzn1.echo-api...",

        "timestamp": "2018-06-20T01:44:15Z",

        "locale": "en-US",

        "status": {

            "code": "200",

            "message": "OK"

        },

        "name": "Buy",

        "payload": {

            "purchaseResult": "ACCEPTED",

            "productId": "amzn1.adg..."

        },

        "token": "correlationToken"

}

Like the upsell, this is your opportunity to quickly thank the customer for their purchase (or congratulate their wise choice), and immediately take them to the experience that uses the purchased product.

…

Alexa: Would you like to buy it?

Customer: Yes.

Alexa: Great! You can now ask me for science questions. Would you like a science question now?

By understanding the different upsell and purchasing scenarios that are available to customers, you can easily add in-skill purchasing to your skill with the customer experience in mind. Check out our technical documentation for more details about adding in-skill purchasing to your voice experience.

How are you using in-skill purchasing to deepen engagement with your customers? Reach out to me on Twitter at @jeffblankenburg to let me know.

More Resources

• Twitch: How to Add In-Skill Purchasing
• In-Skill Purchasing Technical Documentation
• In-Skill Purchasing Code Samples
• Skill Sample: Add In-Skill Products with One-Time Purchases and Subscriptions
• 8 Best Practices for Designing Premium Experiences for Alexa Skills
• Developer Spotlight: In-Skill Purchasing Takes Volley’s Thriving Voice Business to the Next Level

Make Money by Creating Engaging Skills Customers Love

You can make money through Alexa skills using in-skill purchasing or Amazon Pay for Alexa Skills. You can also make money for eligible skills that drive some of the highest customer engagement with Alexa Developer Rewards. Download our guide to learn which product best meets your needs.