Design the Purchase and Cancel Flows

---

When you offer your skill as a paid skill, 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. Paid skills can use the one-time purchase or subscription payment model.

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. When you offer paid skills, your skill should provide value to the customer beyond free content. For best practices to follow when you design voice-first interactions, see the Alexa Design Guide.

Design the purchase suggestion

The purchase suggestion is a way to show the benefit of your skill to customers. The purchase suggestion includes the following parts:

1. An optional transition from any free content your skill provides.

2. A brief description of your skill and its availability to customers.

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

The following example shows the purchase suggestion for a paid skill with a one-time purchase payment.

The example fits the purchase suggestion definition as follows:

1. Skill description: Welcome to Quick Trivia! This fun-filled game offers 10 trivia categories. You can choose between easy, medium, and hard questions.
2. Explicit confirmation: Want to learn more?
3. Configured product offer description: Quick Trivia is a challenging trivia game for all levels.
4. Price details: It costs one dollar and ninety-nine cents plus tax.

Handle a direct purchase

If a customer asks Alexa to buy the skill directly, you can send them to the purchase flow without asking for an explicit confirmation. The following example shows the direct transfer to Alexa for a paid skill with a one-time payment.

Offer a subscription

The purchase suggestion must specifically call out that your paid skill requires a subscription so that customers understand there's a recurring charge. Give them information in the description that tells them what they get with the subscription. Don't include any purchase details.

The following example shows the purchase suggestion and transfer to Alexa for a paid skill subscription.

Offer a trial

Trials are a great way for users to get a sense of the premium content before they purchase it. Don't mention the duration of your trial in your purchase suggestion. Alexa gives the details of the trial in the purchase flow. For details about trial configuration, see billing configuration.

The following example shows the purchase suggestion and transfer to Alexa for a paid skill subscription with a free trial.

This example shows the transfer to Alexa when the trial ends.

Design the post-purchase flow

When your customer buys the skill or accepts a free trial, you create a graceful transfer from the Amazon purchase flow back to your skill.

The following example shows a successful one-time purchase flow and transfer back to the skill.

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 Determine customer entitlement.

Purchase declined

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.

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 skill. 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.

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 paid skill.

Optimize your results

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

• Change the list price of your skill or modify the trial period.
• Update your Purchase Offer Description and purchase suggestion description.
• Re-evaluate your skill content. Do you need more content to make it truly a premium experience? If your skill is older, it might be time to refresh the content.

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

Related topics

• Steps to Build a Paid Skill
• Define Purchase Details

---

---

Last updated: Mar 26, 2024