How to Design for In-Skill Purchasing

Make a Smooth Handoff

In the previous sections we worked really hard to model our upsells on a skilled salesperson. We relied on the energy of the game to draw our customers into the experience and get to know them. Once we know our customer is engaged we are able to ride the wave of maximum efficiency with minimum effort to upsell the right product to our customer which makes it more likely that we will convert the sale.

If you’ve ever bought a car from a dealership, you’ve most likely been transferred to the finance department to discuss final pricing, payment, and signed on the dotted-line to make the purchase official. When your customer says "yes" to your upsell, they too will be handed off to a "finance department" known as the Amazon purchase flow.

The Amazon purchase flow handles all the transaction details and will transition back to your skill whether or not the customer bought the product. Let’s break down what the Amazon purchase flow handles for you:

  1. Converting your product information defined in the product detail page into speech.
  2. Calculating pricing information including discounts for Amazon Prime customers.
  3. Credit transactions with the credit card associated with the account.
  4. Voice PIN verification (if the customer has one set up).
  5. Transaction related errors - invalid payment information, incorrect pin, etc.

Once the transaction is complete it will transition back to your skill. It’s up to you check if transaction was completeddeclined or failed due to an error and respond accordingly.

Since the Amazon purchase flow handles calculating pricing including and applicable discounts, do not include it in your upsell or your product description. Doing so will cause your skill to fail certification.

Now that we understand that our skill and the Amazon purchase flow work together to complete the sale, we need to think about to handle the transitions to and from your skill.

Make a smooth hand-off

When writing your skill dialog, you will need to keep in mind that your skill will be transitioning to and from the Amazon purchase flow. The purchase flow takes your product description and adds the price to the message. The description is limited to 120 characters which is less than a tweet! You’ll need to be very concise.

The Amazon purchase flow doesn’t support Speech Synthesis Markup Language, SSML, so you won’t be able to fully customize how Alexa sounds when giving the product description from the purchase flow.

When designing your hand off, it’s important that you start from your "happy path" which is the best-case scenario in your skill design and think about how to stitch it together with the Amazon purchase flow. You’ll want to play the full conversation multiple times to determine if the transitions are smooth and the changes from skill to Amazon flow and back are not too abrupt. 

Let’s take a look at Justin and Alison act out a smooth transaction. When watching the video, ask yourself, does this conversation flow?

Smooth transitions are important for a consistent experience

Pretty smooth! Here, Justin avoided repeating details that the Amazon purchase flow has said, and it sounds like the Alison is speaking with one entity rather than multiple Justins. After the purchase he asked Alison if she’d like to immediately start playing with her newly purchased product.

The Amazon purchase flow takes our product description and combines it with the pricing information to build the response to our customer who said "yes" to our upsell. Let’s break down the parts into what we wrote vs. what the Amazon purchase flow generated:

Product Description (Limited to 120 characters)

The Home for the Holidays pack from Seattle Super Trivia comes with 50 more questions you can play any time.

Amazon purchase flow

It costs 99 cents plus tax. Would you like to buy it?

There are three situations where a transition can go wrong that you’ll need to be aware of and prepare dialog for each situation:

  1. Transaction declined at the final upsell delivered by Amazon.
  2. An error occurred during the Amazon purchase flow.
  3. Amazon purchase flow is down. This is a very rare situation but requires a unique response in your dialogue.

For each one of these situations, you will need to take special care in how you write your message to communicate with your customer. Since the customer is being handed back to your skill, you need make sure that you don’t repeat anything that they will have heard from the Amazon purchase flow. In these three situations, don’t ask to try again immediately. Instead, include a prompt to continue using the skill without the purchase. If your customer has played through all available free content, you can ask them if they want to play again. For Seattle Super Trivia, we recommend coming back tomorrow for new content and ask if they’d like to replay today’s Free Five.

If your free trial requires an active subscription you will need to apologize to the customer that the content is not available at this time.

When handling transitions, you should:

  1. Avoid repeating information said during the Amazon purchase flow.
  2. Avoid asking to try again immediately.
  3. Prompt to continue using the skill without purchase.

Now that we know what situations to account for and what to avoid in the transition dialog, let’s take a look at what we wrote for Seattle Super Trivia when there was a problem with the transaction.

Skill: "Good game today! All this holiday talk is making me crave turkey. Now you can get 50 more holiday-themed Seattle Super Trivia questions with the Home for the Holidays pack. Want to learn how to get it?"
Customer: "Yes"
<Routes to Amazon Purchase flow>
Amazon: "The Home for the Holidays pack from Seattle Super Trivia comes with 50 more questions you can play any time. It costs 99 cents plus tax. Would you like to buy it?"
Customer: "Yes"
Amazon: "There was a problem with your payment method. Please check your Alexa app for more details."
<routes to skill>
Skill: "No worries. You can always ask me about packs later. Now, want to replay today’s trivia challenge?"
…​

— Seattle Super Trivia

You might have noticed that we didn’t say sorry. It’s not our skill’s fault that the Amazon purchase flow wasn’t able to process the payment method. We avoided repeating any information about the error or the product and we didn’t suggest that they try to make the purchase again. We simply prompted them to continue to playing.

Handling Cancellations & Returns

Just like making a purchase, the Amazon purchase flow also processes cancellations and returns for subscriptions. If the customer wants to cancel their subscription, our skill must pass the customer to the Amazon purchase flow. It will deliver the final terms and ask the customer once more if they still want to cancel. Your skill will need to prompt the customer to continue engaging with any content that they are still entitled to.

If the customer asks to cancel a purchase or to refund a purchase other than a subscription, the skill should deliver a card with information about cancellations or refunds to the customer’s Alexa App. Avoid saying anything that would sound like a guarantee a refund will be issued, since they will need to contact customer service.

You should avoid the following:

Thanks for playing. For a refund, check out the link I sent to your Alexa App.

You should do something like:

Thanks for playing. I’ve sent some information about refunds to your Alexa app.

Understanding Where to Use Voice Over and Amazon Polly

As we discussed, SSML isn’t supported in the product description which the Amazon purchase flow uses to craft the pricing dialog. That means voice-over recordings and Amazon Polly voices are not available in the Amazon purchase flow.

The Amazon purchase flow uses Alexa’s voice and standardized Alexa Presentation Language for devices with screens, which are not customizable. You’ll want to consider which product details would be best delivered by your in-skill voice of choice, and which details will be delivered in the Amazon purchase flow.

Now that we know how to transition to and from the purchase flow, we need to think about how we will provide access to premium content that our customer has purchased.