Design the Purchase and Cancel Flows

---

When you offer in-skill purchasing (ISP), you design the purchase suggestion and the transfer to Alexa to complete the purchase. After the purchase flow completes, you design the flow back to your skill. You also design flows for cancellation and refund. In-skill products should extend or enhance the skill experience and provide value to the customer beyond the free skill content. You can define in-skill products that use the consumable, one-time purchase, and subscription payment models.

For details about how to define in-skill products and associate them with your skill, see Create and Manage In-Skill Products.

Best practices for engaging customers

When you create skills that are highly engaging, user-centric, and built on a foundation of trust, you build a loyal customer base for your skills. Your free content is a showcase of what your skill can do and a foundation on which you can build compelling premium content that can further engage customers. It's important to excite your customers with your free content to build trust so you can ask for the sale at the right time.

For best practices to follow when you design voice-first interactions, see the Alexa Design Guide.

Understand the purchase flow

A customer can ask Alexa to buy a product directly, or you can make a purchase suggestion during the skill flow. If the customer agrees to the purchase suggestion, your skill transfers control to Alexa to complete the purchase. Your skill doesn't take part in the price offered to the customer or the purchase details.

When you offer a product for purchase, you transfer the purchase to Alexa. The following sample utterance shows the transfer from the skill to the Amazon purchase flow and transfer back to the skill after the customer completes the purchase

1. An upsell message that describes the product and asks if the customer wants to learn more. You include the upsell message in the product suggestion. You don't include the upsell message for a direct purchase request.
2. If the customer agrees to learn more, Alexa plays the purchase offer description that you defined when you created the product, gives the pricing details, and then prompts the customer to purchase the product.
3. If the customer agrees to the purchase, Alexa guides the customer through the purchase by using the payment options associated with their Amazon account.
4. After the purchase completes, Alexa transfers control back to your skill.

The following example shows the interaction between Alexa and the customer after your skill transfers the upsell to Alexa.

Design the purchase suggestion

The purchase suggestion or upsell message is a way to offer your in-skill products to customers based on your skill flow or how the customer is currently interacting with your skill. For example, after a customer finishes playing your free trivia categories, you could mention that the skill offers additional categories as part of a monthly subscription.

The purchase suggestion includes the following parts:

1. A starting phrase that gracefully transitions from the current state to the offer.

2. A brief description of the product offered and its availability to customers. Make sure to explain why your product is relevant at this time and what value it has for the customer.

   Important: Be careful not to repeat any information from your configured purchase offer description and don't include pricing details.
3. An explicit confirmation (Yes/No) to confirm interest in the offer, such as, "Want to learn more?"
   If the customer confirms interest, Alexa plays the purchase offer description and the offer price during the Amazon purchase flow.

The following example shows the purchase suggestion for an expansion pack that the skill offers after the customer finishes all free content in the skill. The expansion pack in this example is a one-time purchase.

The example fits the purchase suggestion definition as follows:

1. Transition: You finished all six levels. Great job! If you want more trivia to play, …
   In this transition, your skill acknowledges that the user completed the content and flows nicely into the purchase suggestion.
2. Upsell message: …. you can now get the expansion pack for more challenging trivia questions." The upsell message clearly explains what the expansion pack provide to users.
3. Explicit confirmation: Want to learn more?

Follow purchase suggestion guidance

After the transition, you transfer control to Alexa to complete the purchase flow. In the directive to Alexa, you include an upsell message. Follow the purchase suggestion guidance to create your upsell message.

Do	Don't
Determine the customer's interest in your product.	Never interrupt the customer while they're interacting with your skill content. Wait until there's a pause in the interaction.
Offer relevant products to the customer.	Don't offer a sales pitch. Avoid offering multiple products at the same time.
Summarize what the product provides to the customer.	Don't include pricing details, because Amazon handles pricing. Don't reference the list price, subscription term, or free trial length. Alexa obtains these values from your product description.
End with an explicit confirmation statement.	Don't ask whether they'd like to buy. Customers make a buying decision after this step
Make sure to offer different products each time for variety.	Don't keep suggesting the same product, because it feels like an interruption to the customer.
Only make one suggestion.	If a customer isn't interested, continue where they left off. Don't suggest another product.
Make the customer aware of any quantity or time limits on the product.	Don't leave the customer stuck at a paywall, blocking additional content.

Offer reminders

Reminders are a good way to keep customers engaged with your skill by letting them know what's available. To remind your customers that they can shop for in-skill products, prompt them when they're interacting with your skill. Remember to provide an offer that's relevant to where they are in your skill. Give them examples of products that they can ask for, and then resume the free experience. The customer shouldn't have to respond if they don't want to purchase the product. You risk losing customers when your suggestions begin to feel like interruptions. Start conservatively, then change the frequency over time to find the best approach.

The following example shows a reminder to a customer who is nearly done with the free content.

You can also tell the customer to come back for new content to play during a logical pause in the dialog flow.

Best practices for subscriptions

If you offer a subscription, your upsell message must specifically call out that the product is part of a subscription so that customers understand there's a recurring charge. Give them information in the product suggestion that tells them what they get with the subscription. Don't include any purchase details.

The following example shows the transfer to Alexa for a subscription product suggestion.

Offer a trial

If you use the subscription payment model, you can offer a free trial of the premium content. Trials are a great way for users to preview the product for free for a limited time. Share the benefits that might interest a customer, but refrain from sharing details. Alexa gives the trial details in the purchase flow. For details about trial configuration, see Billing for subscriptions.

The following example shows the transfer to Alexa for a subscription with a free trial.

Best practices for consumables

If you offer consumables, your purchase suggestion must make it clear that the products deplete after use or over time. Be clear about the quantity or duration of the consumable in the product name and description.

The following example shows the purchase suggestion for hints.

Handle a direct purchase

If a customer asks Alexa to buy a product directly, you can send them to the purchase flow without including an upsell message. If the customer doesn't call out the product by name, ask them which product they want, and then send them to the purchase flow.

The following example shows a direct purchase request for a named item.

In the following example the customer makes a direct purchase, but doesn't specify the item by name.

Add a store option to your skill

If your skill already provides a menu of actions when launched, include an option to hear a list of your products. This shopping option gives customers a reliable way to find a product when they're ready to buy.

Include the following items to make it clear that the option is to shop for products to use in your skill:

• Let customers know what to expect by including words like "shop" or "for purchase."
• Make sure to include a shop option in the Help intent for customers who need further assistance.

In the following example, the skill lets the customer know about the store in the welcome message.

For details about how to build a custom intent for a purchase request, see Add support for purchase requests.

Design the post-purchase flow

After your customer accepts or declines the purchase or free trial of the suggested product, create a graceful transfer from the Amazon purchase flow back to your skill. If the customer buys the product, your skill must fulfill the purchased content immediately. For consumables, you might include instructions on how to access or use the new inventory of products that are now available to them. If your customer declines the purchase, move the customer back to the experience that they were enjoying before the purchase flow. If the customer made a direct purchase request, but decides not to purchase your product, remind them that they can buy the product at any time and return them to the current skill experience.

The following example shows a successful subscription purchase. After the purchase flow, your skill starts playing the purchased content.

The following example shows a successful purchase of a 5-hint pack. After the purchase, the skill tells the customer how to access the hints.

If your customer doesn't purchase the suggested product, handle that scenario as well. Depending on the context, if your customer has exhausted all free content and has refused other options, you must end the session.

Pending purchase

At times the purchase flow might take longer than expected. For example, due to local banking regulations, the customer might have to complete payment authentication outside of the Alexa purchase flow. To let the skill know that the purchase is in progress, Alexa returns PENDING_PURCHASE. In turn, use the Get customer entitlement API to check that the purchase completed. If the response indicates that the customer paid for the skill (entitled = ENTITLED), continue with paid content. Otherwise, continue with free content or end the skill session. Don't mention that the purchase is pending.

At the start of the next skill session, make sure that you check the customer entitlement again because the purchase might complete outside the skill session. For more details, see Resume your skill after the purchase flow.

Purchase declined

What if your customer doesn't purchase the product? If there is more content that the customer can access, continue with the skill. However, if the customer exhausted all free content, you must end the session. When your customer declines the purchase, Alexa returns DECLINED to the skill session.

In this example, the skill ends the skill session.

The following example shows a purchase flow in which the customer declines the purchase offer.

Tracking consumable purchases

Consumable products are a great way to allow customers to gain a quick boost or help them overcome a difficult obstacle in a game. Usually, the customer consumes consumable products over time. As a best practice, provide the customer with reminders or the ability to inquire about the balance of their consumables so that they understand what's available to them and know when they're ready to purchase again.

The following example shows a gentle reminder that a 7-day code expires in two days.

The following example shows a customer inquiry on the consumable balance.

Make it easy to cancel

Refunds and cancellations always err on the side of the customer. Never use a request to cancel as an opportunity to remind the customer of the benefits of the products offered. Like purchases, your skill invokes the Amazon cancel flow for refunds and cancellations.

Don't change standard intents, such as Amazon.CancelIntent, AMAZON.StopIntent, to trigger a refund, cancellation, or unsubscribe intent. These intents end your skill session instead of ending the purchase flow. You must invoke the Amazon purchase flow to handle cancellations. For details, see handling refund requests.

The following example shows a cancellation flow in which the customer cancels their monthly subscription.

The following example shows a cancellation flow in which the customer asks for a refund for the one-time purchase.

Optimize your results

If you find that the number of purchases is low, try to change some key items to improve your earnings.

• Change the list price of your products or modify the trial period for your subscription.
• Change the value benefit of your product by changing the product type or quantity. Buying one hint for 99 cents might be an easier sell than unlimited hints for $9.99.
• Update your productOfferDescription and the product summary. Learn more about modifying a product.
• Try changing how often customers hear about your product offerings.
• Reevaluate the content of your product. Should you add more content to make it truly a premium experience? If your content is older, it might be time to add a new product to your skill.
• Consider what products and product types you have that might overlap and confuse the customer. Simplify your store by offering different types of products. A shortcut might be better sold as a consumable whereas premium content might be a better value unlocked as a one-time purchase.

To determine if your improvements are working, track the Offer Impressions and Conversion Rate metrics on the Analytics page of the Alexa developer console.

Related topics

• 8 Best Practices for Designing Premium Experiences for Alexa Skills
• Add ISP Support to Your Skill Code
• Create and manage in-skill products
• Measure Skill Usage
• Speech Synthesis Markup Language

---

---

Last updated: Apr 30, 2024