Build Premium Experiences for Kid Skills in the US

Note: Sign in to the developer console to build or publish your skill.

Note: For a PDF of best practices for designing kid skills with in-skill products, see Design for in-skill purchases in child-directed skills. For sample code, see Premium Facts Sample – Kids Edition in GitHub.

At this time, in-skill products in kid skills is available only 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
Example dialogs
How to determine when to offer a product for purchase
Tailor the experience
Get started
Requirements
Testing
API reference

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

Purchase by Voice, Kid Skills Purchasing, and Purchases Require Approval are ON (default setting)
Purchase by Voice and Kid Skills Purchasing are ON. Purchases Require Approval is OFF
Purchase by Voice or Kid Skills Purchasing is OFF

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
Skill reaches a purchase suggestion trigger
Skill resumes after user accepts the purchase suggestion
User asks about products
User reaches the skill exit
Skill checks for a purchase control setting update

Skill session begins

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

Product status	Guidance
Non-purchasable	Do: Continue the skill session as intended. Don't: Proactively mention or suggest products for purchase. Don't inform the user of the voice purchasing enablement status that the account holder set in the Alexa app, and don't encourage the user to ask the account holder to change the settings.
Purchasable	Do: Make purchase suggestions sometime after the welcome message. If you want to make a purchase suggestion, do provide an upsell message so that Alexa can start the suggestion. Don't: Make purchase suggestions within the welcome message.
Entitled	Do: Provide any content that the user is entitled to. Do make any purchase suggestions for additional products as intended.
Pending	Do: Use the same language that Alexa uses ("We are still waiting for a grown-up's permission to buy that.") and oﬀer any further playable content or bring the skill session to an end. Don't: Encourage the user to ask the account holder about the pending purchase.
Declined or Expired	Do: Provide any playable content or bring the skill session to an end. If necessary to avoid confusion about the alternate experience, tell the user "I didn't get permission", but do not give any information as to why. Don't: Explicitly say whether the purchase was declined or expired. Don't proactively mention or suggest the product for purchase unless a certain amount of time has elapsed. Don't mention or suggest any additional products unless they're absolutely necessary to continue using the skill or there is no more playable content to oﬀer.

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.

Product status	Guidance
Non-purchasable	Do: Provide any further playable content or bring the skill session to an end. Don't: Make a purchase suggestion. Don't inform the user of the voice purchasing enablement status that the account holder set in the Alexa app, and don't encourage the user to ask the account holder to change the settings.
Purchasable	Do: Make the purchase suggestion as intended. If you want to make a purchase suggestion, do provide an upsell message so that Alexa can start the suggestion. Don't: Make a purchase suggestion more than once per skill session unless the user specifically asks "What can I buy?" or something similar.
Entitled	Do: Consider making a purchase suggestion for other products that the user is not entitled to, and surface any content that the user is already entitled to. Don't: Make a purchase suggestion for a product that the user is already entitled to.
Pending	Do: Oﬀer any further playable content or bring the skill session to an end. Don't: Encourage the user to ask the account holder about the pending purchase.
Declined	Don't: Make a purchase suggestion for the same product within the same skill session.
Expired	Do: Consider taking a break from purchase suggestions for any other products for a certain amount of time, to avoid being a nuisance. Don't: Make a purchase suggestion for the same product within the same skill session.

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.

Product status	Guidance
Entitled	Do: Let the user access the purchased product immediately.
Pending	Do: Oﬀer any further playable content or bring the skill session to an end.
Declined	Do: Provide any playable content or bring the skill session to an end. If necessary to avoid confusion about the alternate experience, tell the user "I didn't get permission", but do not give any information as to why. Don't: Explicitly say whether the purchase was declined or expired. Don't make a purchase suggestion or proactively mention the product for a certain amount of time. Don't immediately make purchase suggestions for any additional products unless it's absolutely necessary to continue using the skill or there is no more playable content to oﬀer.

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.

Product status	Guidance
Non-purchasable	Do: Deliver an error such as "I'm sorry, that's not available" and oﬀer any further playable content. Don't: Make a purchase suggestion or tell the user about products for purchase. Don't inform the user of the voice purchasing enablement status that the account holder set in the Alexa app, and don't encourage the user to ask the account holder to change the settings.
Purchasable	Do: Give a generic answer about premium content and, if you like, make a purchase suggestion ("What can I buy?") or give any information about previous purchases that were made "What did I buy?" If you want to make a purchase suggestion, do provide an upsell message so that Alexa can start the suggestion.
Entitled	Do: Explain any premium content that the user is entitled to. Do deliver a card to the Alexa app with additional purchase details if more than one purchase has been made. Do make a purchase suggestion for any additional products depending on the time elapsed since the previous state change.
Pending	Do: Explain any premium content that the user is entitled to. Do deliver a card to the Alexa app with additional purchase details if more than one purchase has been made. Finally, route the user back to their previous skill state and/or oﬀer any further playable content. Don't: Encourage the user to ask the account holder about the pending purchase.
Declined	Do: Explain any premium content that the user is entitled to. Do deliver a card to the Alexa app with additional purchase details if more than one purchase has been made. Do make a purchase suggestion depending on time elapsed since the decline.
Expired	Do: Explain any premium content that the user is entitled to. Do deliver a card to the Alexa app with additional purchase details if more than one purchase has been made. Proactively mention products for purchase or make a purchase suggestion for any additional products depending on time elapsed since expiration.

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

Product status	Guidance
Non-purchasable	Do: Deliver a standard exit message. Don't: Make a purchase suggestion or proactively mention products for purchase.
Purchasable	Do: Make a purchase suggestion or proactively mention products for purchase, if desired. If you want to make a purchase suggestion, do provide an upsell message so that Alexa can start the suggestion. Don't: Make a purchase suggestion more than once per skill session unless the user specifically asks "What can I buy?" or something similar.
Entitled	Do: Consider making a purchase suggestion for other products that the user is not entitled to. Don't: Make a purchase suggestion for a product that the user is already entitled to.
Pending	Do: Deliver an exit message as planned without any proactive messaging or purchase suggestions about products for purchase. It is acceptable to tell the user to come back to the skill later. Use the same language that Alexa uses ("We are still waiting for a grown-up's permission to buy that.").
Declined or Expired	Do: Deliver an exit message as intended. Don't: Make a purchase suggestion or proactively mention products for purchase.

Skill checks for a purchase control setting update

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

Product status	Guidance
Non-purchasable	Do: Continue the skill session as intended. Don't: Make purchase suggestions or proactively mention products for purchase.
Purchasable	Do: Handle this case at your discretion.
Entitled	Do: If the user was recently in "Pending" status, inform the user their new content is ready to play. Ask if they'd like to play it now, or route them to the new content automatically.
Pending	Do: Continue the skill experience as intended. Don't: Mention the pending status to the user.
Declined or Expired	Do: Provide any playable content or bring the skill session to an end. If necessary to avoid confusion about the alternate experience, tell the user "I didn't get permission", but do not give any information as to why. Don't: Explicitly say whether the purchase was declined or expired. Don't make a purchase suggestion or proactive messaging about the product for a certain amount of time. Don't immediately make purchase suggestions for any additional products unless it's absolutely necessary to continue using the skill or there is no more playable content to oﬀer.

Get started

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

Review the requirements.
(Optional) Check out the sample code, Premium Facts Sample – Kids Edition, in GitHub.
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?
Learn how to add ISP support to your skill code.
Learn how to extend voice purchasing to kid skills by reading the current page.
Test your skill as described in Testing.
Submit your skill for certification. Note that if you add, update, or discontinue products, you must submit your skill for recertification.
(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.

Note: For general information about testing skills that offer in-skill purchases, see Test In-Skill Purchasing Skills.

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