Amazon have been super busy recently, and one of the most exciting announcements for me to be able to look into has been the ability to have in-skill purchasing.

What this means is that your skill can now ask a user to make a purchase without ever leaving the echo or having to pick up the companion app. In-skill purchasing is for digital content, and it is available in two flavours:

• Subscription: your user pays so much a month, and you give them extra functionality such as premium content or exclusive audio.
• Entitlement: a one off purchase for new content – and it’s important that we understand that it’s content; it’s a new level in a game or an article they can now listen to any time they like, it’s not for consumables like buying extra lives in a game.

So this probably has your mind thinking of the possibilities, but it’s the way that Amazon allow you to do it which is so fabulous. Your skill never has to worry about taking a payment or asking the right questions to get a users details!

So how does it work? Well first of all you have to set up an in-skill product, something the user can buy. As of this article this process has to happen via the ASK CLI, and is a multi step process I won’t go into (I want to focus on the .NET Skill side of things) but as always the documentation is great so here’s how to use the ASK CLI to create in-skill purchases

Once you have a product, you can ask your user at an opportune time if they want to purchase it.

“hey, if you like our free content, would you be interested in a subscription for all our premium content?”

You’ll notice it doesn’t mention price etc. This is because the rules about the price are determined by your products and Amazon (there are rules about prime members getting some extra benefit, such as a lower cost etc.) so your skill won’t know the exact deal the user is going to get.

But the important thing is you have a product to offer, in this case a subscription, and the user has said yes they’re interested. So what do we do? Well first of all we ensure we know how to get to the Amazon docs for guidance on the rules regarding how to add in-skill purchasing to a custom skill, then we add the Alexa In-Skill Purchasing NuGet package to the project, then we look at each of the following steps:

Starting the purchasing process

As we’ve said Amazon handles all the purchasing itself, so in terms of starting a purchase we send a response with a new directive added to it. This directive contains two pieces of information:

• Product ID: This you’ll get as part of the product creation process with the ASK CLI.
• Token: This is your way of ensuring you can match the notification of a particular sale back to the purchase.

var skillResponse = ResponseBuilder.Empty();
skillResponse.Response.ShouldEndSession = true;
skillResponse.
            skillResponse.Response.Directives.Add(
                new BuyDirective(productId,token)
            );

This makes the whole thing really straight forward to kick off. Amazon handles the interaction from that point onward and our skill is simply told about the response, which is the next thing we deal with.

Handling a purchase

So the user has the choice of making the purchase or changing their mind. Either way the skill is told of the result and the skill can pick up straight where it left off.

For this part of the process we handle a new response type. Firstly by ensuring we can handle it in our response

public HandlerClass(){
  ConnectionResponseHandler.AddToRequestConverter();
}

then we ensure it’s handled in our code by getting the new request type and finding out the result of the transaction

switch(skillRequest.Request)
{
case ConnectionResponseRequest paymentDetail:
//Can be any of the PurchaseResult constants:
//Accepted, Declined, AlreadyPurchased or Error
if(paymentDetail.Name == PaymentType.Buy)
{
var result = paymentDetail.Payload.PurchaseResult;
var token = paymentdetail.Token;
}
}

Using the token we can wire up anything we had to set before requesting the purchase. If the result of the purchase was that it was Declined, then the skill should try and make it as seamless as possible to pick up where it left off and give the user a good experience with your skill.

You’ll also notice that we check the payment type. That’s because the same request object is used for cancellations and upsells too – so make sure you handle the interaction correctly and double check what’s going on.

Handling a cancellation

Once the user has made a purchase for a subscription, there’s always the possibility of them changing their mind and cancelling. This is handled in the same hands off approach as before. The request you get back for a cancellation is the same type as the purchase – so we won’t copy that code, and the response to start the cancellation is pretty similar too.

var skillResponse = ResponseBuilder.Empty();
skillResponse.Response.ShouldEndSession = true;
skillResponse.
            skillResponse.Response.Directives.Add(
                new CancelDirective(productId,token)
            );

Checking purchase state for a customer

Lastly, when a user uses your skill you may need to check to see what the state is in regards to their purchasing of your product. There’s an API call you can make to check on that. There’s a call to get all products, but this example helps you check on just one:

var client = await new InSkillProductsClient(skillRequest);
var productDetail = client.GetProduct("productId");
if(productDetail.Entitled == Entitlement.Entitled)
{
  //They bought it - give them the good stuff!
}

So as you can see although the functionality involved in in-skill purchases is extremely comprehensive, it’s through several light touches to your skill that it becomes a smooth and natural experience for your users.