Build Premium Experiences for Kid Skills in the US


You can offer two types of in-skill products (ISPs) in kid skills – subscriptions and one-time purchases. In many ways, incorporating ISPs into kid skills is similar to incorporating ISPs into non-kid skills. For example, all ISP operations – including updates, removal, deletion, association and disassociation of ISPs with a skill – work similarly for kid skills as they do for non-kid skills. As with non-kid skills, you can use the developer console or the Alexa Skills Kit Command-Line Interface (ASK CLI) to develop the skill.

However, kid skills must take an additional factor – parental control – into account. Using the Alexa app, parents can enable and disable voice purchasing in kid skills, and can also choose whether they would like to approve each purchase individually. Your skill must therefore provide an appropriate experience based on the state of voice purchasing (enabled or disabled), and the state of the product (pending parent approval, denied parent approval, and so on). Also, kid skills cannot offer ISPs for a price higher than $9.99 USD, or sell ISPs of type consumable. At this time, ISP in kid skills is available only in the US.

This topic describes how parents can control voice purchasing for kid skills, explains the APIs that you use to check purchase settings and product status, and provides guidance on how to handle various scenarios.

For simplicity, we use user to refer to the skill user, account holder to refer to the registered account holder, and product to refer to an in-skill product with a particular ASIN.

How parental control works

The Alexa app contains four settings that, combined, enable the account holder to customize the permissions of voice purchasing in kid skills. The settings are as follows:

Location in Alexa app: Settings > Alexa Account > Voice Purchasing

  • Purchase by Voice (ON/OFF)
  • Voice Code (ON/OFF)

Location in Alexa app: Settings > Alexa Account > Voice Purchasing > Kid Skills Purchasing

  • Kid Skills Purchasing (ON/OFF)
  • Purchases Require Approval (ON/OFF)

Based on these settings, the account holder can choose one of the following experiences for voice purchasing for kid skills:

  • Purchase by Voice, Kid Skills Purchasing, and Purchases Require Approval are ON – (Default) The user of a kid skill can request purchases, but the account holder must approve each purchase before the user can access it. The account holder receives a notification with a link to the purchase order details through SMS or email. They have 24 hours to approve the purchase; otherwise, the request expires.
  • Purchase by Voice and Kid Skills Purchasing are ON. Purchases Require Approval is OFF – The user of a kid skill can purchase and immediately access purchased content without requiring additional approval by the account holder. However, if Voice Code is enabled, the user must say the voice code before they can purchase the content.
  • Purchase by Voice or Kid Skills Purchasing is OFF – The user of a kid skill cannot purchase any premium content if Kid Skills Purchasing or Purchase by Voice is off. However, the user has access to any premium content that was purchased before these settings were disabled.

Example dialogs

This section contains example dialogs for each of the three scenarios described previously. Note that, as with all skills that sell products, the dialogs have three participants: the user, the skill (before and after the purchase flow), and Alexa (the purchase flow).

Dialog: Purchase by Voice, Kid Skills Purchasing, and Purchases Require Approval are ON (default setting)

In this example, the skill offers a product that the user wants. Because the account holder has set voice purchasing for kid skills to require approval for each purchase, the user cannot use the product until the account holder approves the transaction.

Dialog: Purchase by Voice and Kid Skills Purchasing are ON. Purchases Require Approval is OFF

In this example, because the account holder has set voice purchasing for kid skills not to require additional approval for each purchase, the user can access the product immediately after requesting it.

Dialog: Purchase by Voice or Kid Skills Purchasing is OFF

In this example, because the account holder has disabled voice purchasing, the skill does not make any purchase suggestions.

How to determine when to offer a product for purchase

How, and whether, your skill offers a product for purchase at any given time depends on the state of the product, and the voice purchasing settings that the account holder has set. To determine this information, you use one or a combination of the following HTTP GET APIs:

  • voicePurchasing – Gets the voice purchasing in kid skills setting that the account holder has chosen using the Alexa app.
  • inSkillProducts – Gets information about the specified product, such as the product type and whether it is purchasable by the account.
  • inSkillProductsTransactions – Provides information about transactions, such as if a previous purchase request was denied.

This section describes the states that a product can be in at any given time, the easiest way to find or infer this information using the available ISP APIs, and how to handle each case. Later, we provide more detailed guidance on how to handle different scenarios.

Product state How to find or infer it How to handle it

Non-purchasable

The voicePurchasing API returns false.

You cannot suggest any products or mention that there are additional products to purchase.

Purchasable

The voicePurchasing API returns true, AND the inSkillProducts API purchasable field is PURCHASABLE.

You can suggest the product.

Note that when the product state is Purchasable, you must first provide an upsell message in order for Alexa to start the purchase suggestion.

Entitled

The inSkillProducts API entitled field is ENTITLED.

You can let the user access the product, and you can suggest other products.

Pending

The inSkillProductsTransactions API shows the latest transaction for the product is PENDING_APPROVAL_BY_PARENT.

You cannot let the user access the product, but you can let them know that the product is pending their account holder's approval.

Declined

The inSkillProductsTransactions API shows the latest transaction for the product is DENIED_BY_PARENT.

You cannot suggest the same product again in the same session, but you can suggest other products. If the user declines a product three times, Amazon will mark the product as non-purchasable for 30 days.

Expired

The inSkillProductsTransactions API shows the latest transaction for the product is EXPIRED_NO_ACTION_BY_PARENT.

After a length of time, you can suggest the product to the user again.

Tailor the experience

Your skill must provide an appropriate experience based on whether the account holder requires approval for each purchase, declined the purchase, let the purchase request expire, or turned off voice purchasing in kid skills altogether. It is important to be transparent about what kind – and how much – content you are providing for purchase, while maintaining customer trust and reducing annoyance or confusion on the part of both parents and children.

This section provides guidance on what your skill should do, and not do, at key points within the kid skill flow based on the status of the product. For the requirements that your skill must meet, see Requirements.

Skill session begins

Scenario: The user opens the skill. For example, the user says, "Alexa, play Animal Quiz."

Skill reaches a purchase suggestion trigger

Scenario: The user reaches a purchase suggestion trigger in the skill. For example, they finished all of the free quizzes, and there are additional quizzes available for purchase.

Skill resumes after user accepts the purchase suggestion

Scenario: The user requests the purchase, Alexa gives the purchase details, and then Alexa returns the user to the skill.

User asks about products

Scenario: The user asks the skill, "What can I buy?", "What did I buy?", "I want to buy [product]", or something similar.

User reaches the skill exit

Scenario: The user reaches the skill-exit method other than through explicitly saying "Stop" or "Exit". For example, the skill asks, "Would you like to take any more quizzes?" and the user says, "No".

Skill checks for a purchase control setting update

Scenario: The skill checks whether the account holder has changed the purchase control setting.

Get started

To create a kid skill that includes voice purchasing, do the following:

  1. Review the requirements.
  2. (Optional) Check out the sample code, Premium Facts Sample – Kids Edition, in GitHub.
  3. Create a custom skill. When you create the skill, choose Yes for the following questions on the skill's Distribution > Privacy & Compliance page.
    • Does this skill allow users to make purchases or spend real money?
    • Is this skill directed to or does it target children under the age of 13?
  4. Learn how to add ISP support to your skill code.
  5. Learn how to extend voice purchasing to kid skills by reading the current page.
  6. Test your skill as described in Testing.
  7. Submit your skill for certification. Note that if you add, update, or discontinue products, you must submit your skill for recertification.
  8. (Optional) Check the Monetization metrics for your skill.

Requirements

Kid skills that offer voice purchasing must meet the following requirements:

Testing

Before you submit your skill for certification, make sure to do the following tests:

Testing Amazon FreeTime Unlimited skills

Note that because some kid skills are part of the Amazon FreeTime Unlimited catalog, you might need to test with different accounts to validate that different types of users have the right experience. We recommend that you test with the following accounts:

  • Primary account – This account does not have an Amazon FreeTime Unlimited subscription attached. You want your primary Amazon account to be able to test purchases end to end.
  • Secondary account – You should create one or more new Amazon accounts with an Amazon FreeTime Unlimited (FTU) subscription and use one-week trials to verify the correct skill behavior. Use the skill beta testing tool to add the skill to your FTU-subscribed account. After you accept the invitation in your FTU account, you will see the skill in the Alexa app under Your Skills. Ensure that the Alexa device that you are testing with is not in FreeTime mode.

Tests for kid skills that offer in-skill products

Test Expected results What to do

A member of Amazon FreeTime Unlimited uses a FreeTime Unlimited skill.

All content is free, and there are no purchase suggestions or purchase prompts.

Make sure that the user has access to any content for which the inSkillProducts API returns an ENTITLED value for the entitled field and AUTO_ENTITLED value for the entitlementReason field.

The user attempts to purchase a product while voice purchasing for kids is turned off.

The skill gracefully continues the session after Alexa does not proceed with the purchase.

Make sure that if the user tries to make a purchase while the voicePurchasing API returns false, you continue the session using free or previously purchased content.

The user attempts to make a purchase while voice purchasing for kids is set to require approval for each purchase.

The skill gracefully continues the session using free or previously purchased content while the purchase is pending approval.

Make sure that, after the user requests a purchase, you call the inSkillProductsTransactions API. If the status of the latest transaction is PENDING_APPROVAL_BY_PARENT, tell the user that you are waiting for permission, and then offer them free or previously purchased content.

The user tries to repurchase a product that is pending permission from the account holder.

The skill does not allow the user to repurchase the product that is pending permission. Alexa informs the user that the purchase is pending approval.

Make sure that, after the user requests a purchase, you call the inSkillProductsTransactions API. If the status of the latest transaction is PENDING_APPROVAL_BY_PARENT, tell the user that you are waiting for permission, and then offer them free or previously purchased content.

The user tries to use a purchased product when they reopen a new skill session after the account holder approved the purchase.

The skill allows the user to use the product when they start the new skill session.

Make sure that the user has access to any content for which the inSkillProducts API returns an entitled field value of ENTITLED.

The user tries to interact with the skill after a purchase approval is denied.

After the previous purchase request is declined or expired, the skill allows the user to interact with the skill.

Make sure that you call the inSkillProductsTransactions API. If the status of the latest transaction is DENIED_BY_PARENT or EXPIRED_NO_ACTION_BY_PARENT, ensure that the user can still use free or previously purchased content.

The user uses the skill when voice purchasing is disabled.

The skill does not make any purchase suggestions.

Make sure that when the voicePurchasing API returns false, the user can use free or previously purchased content, and you do not offer any purchase suggestions.

The user asks for a refund.

Refund info is provided even if the user has voice purchasing turned off.

See Handle a refund or cancel request and make sure that the user has access to any previously purchased or free content.

API reference

In addition to the inSkillProducts API, which other skills that sell products use, kid skills use the voicePurchasing API and inSkillProductsTransactions API described in this section.

voicePurchasing API

Gets the purchase control setting, which the account holder chooses in the Alexa app. This API only returns results for kid skills.

Request

GET /v1/users/~current/skills/~current/settings/voicePurchasing.enabled
Host: {event.context.System.apiEndpoint}
Authorization: Bearer {event.context.System.apiAccessToken}

Parameters

Name Located in Description Type Required
authorization header Access token used for authentication and authorization. This is passed to the user in the SPI call. String Yes

Example

Copied to clipboard.

// Check to see if the user's kid skill purchasing setting is ON.
async function getGlobalISPPermission (handlerInput) {
  const monetizationService = handlerInput.serviceClientFactory.getMonetizationServiceClient();
  const voicePurchaseSetting = await monetizationService.getVoicePurchaseSetting();
  // The returned object is a boolean
  return voicePurchaseSetting;
}

Response

Code Description Type
200 Returns true or false. Boolean
400 Invalid request. Error
401 The authentication token is invalid or doesn't have access to make this request. Error
403 Enablement not found, permission is not granted, or you do not have access to this API. Error
500 Internal server error. Error

inSkillProductsTransactions API

Provides information about transactions, such as if a previous purchase request was denied. You can query transactions by transaction status or date. This API applies to kid skills only, and is only relevant when kid skill purchasing requires parental approval.

Request

GET /v1/users/~current/skills/~current/inSkillProductsTransactions
Host: {event.context.System.apiEndpoint}
Accept-Language: {event.request.locale}
Authorization: Bearer {event.context.System.apiAccessToken}

Parameters

Name Located in Description Type Required
authorization header Access token used for authentication and authorization. This is passed to the user in the SPI call. String Yes
Accept-Language header User's locale/language in context. String Yes
productId query Product ID of the product to get transactions for. String No
status query Filter products based on the provided status. String. For valid values, see Transaction status. No
fromLastModifiedTime query Fetches transactions with the last-modified date greater or equal to this value. ISO 8601 string. Example: 2019-04-30T18:21:07.52Z No
toLastModifiedTime query Fetches transactions with the last-modified date less than or equal to this value. ISO 8601 string. Example: 2019-04-30T18:21:07.52Z No
nextToken query Indicates the response is truncated. The token value is used in the next request as the continuation-token to list the next set of objects. This token is an opaque value intended for use by the service. Token expires in 24 hours. String No
maxResults query Sets the maximum number of results returned in the response body. Set this value to retrieve less than the upper limit of 50. If there are additional results that satisfy the search criteria, but they were not returned because maxResults was exceeded, the response contains isTruncated = true. Number between 1 and 50 No

Example

Copied to clipboard.

// Get the status for all purchase transactions that require approval.
async function getISPTransactions (handlerInput) {
 const locale = handlerInput.requestEnvelope.request.locale;
 const monetizationService = handlerInput.serviceClientFactory.getMonetizationServiceClient();
 const transactions = await monetizationService.getInSkillProductsTransactions(locale)
 // The returned object is an array containing all transactions (pending or finalized)
 return transactions.results;
}

Response

Code Description Type
200 Returns transactions that meet the request criteria on success. Transactions
400 Invalid request. Error
401 The authentication token is invalid or doesn't have access to make this request. Error
403 Enablement not found, permission is not granted, or you do not have access to this API. Error
412 This API does not yet support non-kid skills. Error
500 Internal server error. Error

A successful response contains a list of transactions sorted by lastModifiedTime. The latest transaction is at index 0. By default, the list truncates to a maximum of 50 transactions. If kid skill purchasing does not require parental approval, transactions are not logged.

{
   "status": "PENDING_APPROVAL_BY_PARENT", // See Transaction status section for other values
   "productId": "amzn1.adg.product.unique-id-1",
   "createdTime": "2018-11-14T22:21:00.52Z",
   "lastModifiedTime": "2018-11-14T22:21:00.52Z"
}
Name Description Type
status Status of transaction. String. For valid values, see Transaction status.
productId The product that this transaction applies to. String
createdTime The time at which transaction's was initiated. ISO 8601 string
lastModifiedTime The time at which transaction's status was last updated. ISO 8601 string

Sample 200 response

This sample response shows transactions for three products. The transactions, from the oldest (bottom) to the newest (top) indicate the following scenario:

  • The first product was requested by the user and approved by the account holder.
  • The second product was requested by the user and denied by the account holder.
  • The third product was requested by the user, and the approval period expired before the account holder approved it.
{
   "results": [
    	{
          "status": "PENDING_APPROVAL_BY_PARENT",
          "productId": "amzn1.adg.product.unique-id-4",
          "createdTime": "2018-11-23T12:23:10.52Z",
          "lastModifiedTime": "2018-11-23T12:23:10.52Z"
       },
       {
          "status": "PENDING_APPROVAL_BY_PARENT",
          "productId": "amzn1.adg.product.unique-id-3",
          "createdTime": "2018-11-23T11:21:10.52Z",
          "lastModifiedTime": "2018-11-23T11:21:10.52Z"
       },
       {
          "status": "EXPIRED_NO_ACTION_BY_PARENT",
          "productId": "amzn1.adg.product.unique-id-3",
          "createdTime": "2018-11-20T12:23:10.52Z",
          "lastModifiedTime": "2018-11-21T12:23:10.52Z"
       },
       {
          "status": "DENIED_BY_PARENT",
          "productId": "amzn1.adg.product.unique-id-2",
          "createdTime": "2018-11-15T11:03:07.52Z",
          "lastModifiedTime": "2018-11-15T11:03:08.52Z"
       },
       {
          "status": "APPROVED_BY_PARENT",
          "productId": "amzn1.adg.product.unique-id-1",
          "createdTime": "2018-11-14T22:21:00.52Z",
          "lastModifiedTime": "2018-11-14T22:22:00.52Z"
       }
   ],
   "metadata": {
      "resultSet": {
         "nextToken": "EXAMPLE123456789ABCDEFGHI"
       }
   }
}

Transaction status

  • PENDING_APPROVAL_BY_PARENT: The purchase request has been made but is still waiting for approval from the account holder.
  • APPROVED_BY_PARENT: The purchase request was approved by the account holder and the order was successfully placed.
  • DENIED_BY_PARENT: The purchase request was denied by the account holder.
  • EXPIRED_NO_ACTION_BY_PARENT: The purchase request was made, but the account holder did not respond to the request within a stipulated time period and now that request is expired.
  • ERROR: An error occurred when processing an order. This can be due to a user, payment, or internal service error.

Last updated: Sep 14, 2022