In-Skill Product Schema

The in-skill product schema is a JSON representation of digital products available for the customer to purchase in your skill. You can define the following types of in-skill products:

  • One-time purchase – Premium-skill content that doesn't expire. Also called entitlement.
  • Consumable – Premium content that a customer can purchase, deplete when used, and then purchased again.
  • Subscription – Offer access to premium skill content for a period of time, charged on a recurring basis until the customer cancels the subscription.

For more details about in-skill products and in-skill purchasing, see Understand In-Skill Purchasing.

This reference defines the properties that make up the in-skill product schema.

Product

The in-skill product schema includes the following properties of the Product object.

Property Description Type

version

Version of product definition.

String

type

Product payment model type.
Valid values: CONSUMABLE, ENTITLEMENT, SUBSCRIPTION.

String

productId

Primary identifier for the product assigned by Amazon.

String

referenceName

Product reference name selected by the developer. Use this name when you refer to the product in your skill code.
Valid value: 3–50 alphanumeric characters and underscore.

String

purchasableState

Indicates whether customers can purchase the product.
Valid values: PURCHASABLE, NOT_PURCHASABLE.

When the state is NOT_PURCHASABLE, the product is deactivated and customers can no longer purchase the product in a live skill. However, customers who purchased the product previously continue to have access to the product For a subscription, existing customers have access to the product for the remainder of the subscription term. A deactivated subscription doesn't renew. Your skill must continue to support deactivated products.

String

promotableState

Indicates that this product is available for in-skill purchasing only. Or, indicates that the product is available to purchase with both in-skill purchasing and on the Amazon retail site.
Valid values: IN_SKILL_ONLY, ALL_AMAZON_CHANNELS.

String

subscriptionInformaton

(Optional) Describes the billing frequency and trial period length for the subscription products.

SubscriptionInformation object

publishingInformation

Defines how to present the product to customers.

PublishingInformation object

privacyAndCompliance

Defines the product's privacy policy by locale.

PrivacyAndCompliance object

testingInstructions

Instructions and test credentials for certification team to use to test the product.
Valid value: 1–4000 alphanumeric characters

String

PublishingInformation object

Property Description Type

locales

Product information for each supported locale.

Map of Locale objects

distributionCountries

List of countries and regions where the product is available.
For more details, see Countries and regions that support in-skill products.
Formatted in ISO 3166-1 alpha-2.

Array of strings

pricing

Localized pricing information defined for the product.

Map of Pricing objects

taxInformation

Provides the tax information for the product.

Object

taxInformation.category

Tax category for the product.
For more details, see Tax category field.
Valid values: INFORMATION_SERVICES, NEWSPAPERS, PERIODICALS, SOFTWARE, STREAMING_RADIO, VIDEO.

Object

Locale object

The Locale object describes publishing information specific to a language and country. Format the <locale> name as a 2-letter language code, dash, 2-letter country/region code, for example, en-US. For valid string values, see Locales that support in-skill products.

Property Description Type

<locale>.name

Name of the product in this locale. Included in the purchase confirmation prompts, purchasing cards in the Alexa app, and email receipts.
Valid value: 2–50 characters.

String

<locale>.summary

Brief description of the product.
Valid value: 1–160 characters.

String

<locale>.description

Full explanation of the product, including functionality and any applicable prerequisites.
Valid value: 1–4000 characters.

String

<locale>.smallIconUri

URI to an icon that represents the in-skill product. The icon must be a 108 x 108 pixels in PNG format with transparency. Amazon recommends that the image has 75 pixel padding on all sides because the image displays as rounded.
You can reuse the small icon associated with your skill, or provide a unique image to represent your in-skill product. Use a publicly-accessible URL, or if you use the skill package format, use a relative path to the skill.json file, such as file://assets/images/isp1/en-US_smallIcon.png.

String

<locale>.largeIconUri

URI to an icon that represents the in-skill product. The icon must be a 512 x 512 pixels in PNG format with transparency. Amazon recommends that the image has 75 pixel padding on all sides because the image displays as rounded.
You can reuse the large icon associated with your skill, or provide a unique image to represent your in-skill product. Use a publicly-accessible URL, or if you use the skill package format, use a relative path to the skill.json file, such as file://assets/images/isp1/en-US_largecon.png.

String

<locale>.examplePhrases

List of example phrases that illustrate how users can ask for your product in the language of the locale.

Valid value for each phrase: 2–200 characters.
Maximum: 3 phrases.

Array of string

<locale>.keywords

Phrases that describe the product offering.
Valid value: 1–150 characters.
Maximum: 30 keywords.

Array of string

<locale>.customProductPrompts

Defines what the customer hears and sees after they purchase the product.

Object

<locale>.customProductPrompts.purchasePromptDescription

Brief description of the product that the customer hears when they purchase or cancel the product. Don't repeat the same phrases that customers have already heard. For more details, see Design a Good Customer Experience.
Valid value: 1–160 characters.

Include the following items in the description:

  • Product name. Use {PREMIUM_CONTENT_TITLE} as a token for the name field. Don't use "{" or "}" anywhere else in the prompt.
  • Brief description about what's unique about the product.

String

<locale>.customProductPrompts.boughtCardDescription

Description of the product that displays on the skill card in the Alexa app after a customer purchases or cancels the product. You can included the placeholder, {PREMIUM_CONTENT_TITLE}.
Valid value: 1–160 characters.

String

Pricing object

A Pricing object contain details about the default price of a product in the specified Amazon retail marketplace, such as amazon.com. For valid string values, see Marketplaces that support in-skill products.

Property Description Type

<marketplace>.releaseDate

Date and time when customers can purchase and use the product.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

<marketplace>.defaultPriceListing

Localized pricing information defined for the product.

Object

<marketplace>.defaultPriceListing.price

List price of the product.
For minimum and maximum price values, see Price ranges for in-skill products.

Number

<marketplace>.defaultPriceListing.primeMemberPrice

List price of the product for Amazon Prime members.

Number

defaultPriceListing.currency

Currency code for the price.
Defined in ISO 4217 format.
For supported currency codes, see Price ranges for in-skill products.

String

PrivacyAndCompliance object

The PrivacyAndCompliance object defines your privacy policy in each supported local. The object includes a map of locales.

Property Description Type

<locale>

2-letter language code and 2-letter country/region code, for example, en-US. For valid string values, see Locales that support in-skill products.
Formatted as: XX-XX

Object

<locale>.privacyPolicyUrl

Valid URL to the privacy policy for this locale.

String

SubscriptionInformation object

Describes the billing frequency and trial period length for a subscription. Include for subscription payment model only.

Property Description Type

subscriptionPaymentFrequency

Describes the billing cycle for the subscription.
Valid values: MONTHLY, YEARLY.

String

subscriptionTrialPeriodDays

Indicates the duration of the trial period, in days.
Valid values: 0 – 90.

Integer

Consumable product example

The following example shows a consumable product definition.

{
    "version": "1.0",
    "type": "CONSUMABLE",
    "referenceName": "five_hint_pack",
    "publishingInformation": {
        "locales": {
            "en-US": {
                "name": "Five-hint pack",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "Five hints you can use if you get stuck on a question.",
                "description": "The five-hint pack gives you five hints you can use any time you can't answer a question. You can use your hints at any point in the game.",
                "examplePhrases": [
                    "Alexa, buy hints",
                    "Alexa, give me a hint"
                ],
                "keywords": [
                    "games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} provides you with five hints you can use at any time.",
                    "boughtCardDescription": "Use your hints in the {PREMIUM_CONTENT_TITLE} when you don't know an answer by asking Alexa to use a hint."
                }
            },
            "en-GB": {
                "name": "Five-hint pack",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "Five hints you can use if you get stuck on a question.",
                "description": "The five-hint pack gives you five hints you can use any time you can't answer a question. You can use your hints at any point in the game.",
                "examplePhrases": [
                    "Alexa, buy hints",
                    "Alexa, give me a hint"
                ],
                "keywords": [
                    "games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} provides you with five hints you can use at any time.",
                    "boughtCardDescription": "Use your hints in the {PREMIUM_CONTENT_TITLE} when you don't know an answer by asking Alexa to use a hint."
                }
            },
            "de-DE": {
                "name": "Five-hint pack",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "Five hints you can use if you get stuck on a question.",
                "description": "The five-hint pack gives you five hints you can use any time you can't answer a question. You can use your hints at any point in the game.",
                "examplePhrases": [
                    "Alexa, buy hints",
                    "Alexa, give me a hint"
                ],
                "keywords": [
                    "games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} provides you with five hints you can use at any time.",
                    "boughtCardDescription": "Use your hints in the {PREMIUM_CONTENT_TITLE} when you don't know an answer by asking Alexa to use a hint."
                }
            }
        },
        "distributionCountries": [ "AT", "DE", "LI", "LU", "US" ],
        "pricing": {
            "amazon.com": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 0.99,
                    "currency": "USD"
                }
            },
            "amazon.co.uk": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 0.54,
                    "currency": "GBP"
                }
            },
            "amazon.de": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.80,
                    "currency": "EUR"
                }
            }
        },
        "taxInformation": {
            "category": "SOFTWARE"
        }
    },
    "privacyAndCompliance": {
        "locales": {
            "en-US": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            },
            "en-GB": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            },
            "de-DE": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            }
        }
    },
    "testingInstructions": "Start a game. When asked a question, ask Alexa for a hint.",
    "purchasableState": "PURCHASABLE",
    "promotableState": "ALL_AMAZON_CHANNELS"
}

One-time purchase product example

The following example shows a one-time purchase product definition.

{
    "version": "1.0",
    "type": "ENTITLEMENT",
    "referenceName": "cave_quest",
    "publishingInformation": {
        "locales": {
            "en-US": {
                "name": "Cave Quest",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "  5 new adventures for your collection",
                "description": "The Cave Quest expansion pack includes 5 brand new adventures for your collection. Venture into even deeper and darker caves with Emerald and her friends, and collect up to 30 unique treasures. Adventures will automatically be playable once you've completed your purchase, and you can play them as often as you'd like.",
                "examplePhrases": [
                    "Alexa, play cave quest",
                    "Alexa, buy cave quest"
                ],
                "keywords": [
                    "Games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes 5 new adventures with Emerald and her friends.",
                    "boughtCardDescription": "Enjoy {PREMIUM_CONTENT_TITLE} by asking Alexa to play cave quest."
                }
            },
            "en-GB": {
                "name": "Cave Quest",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "  5 new adventures for your collection",
                "description": "The Cave Quest expansion pack includes 5 brand new adventures for your collection. Venture into even deeper and darker caves with Emerald and her friends, and collect up to 30 unique treasures. Adventures will automatically be playable once you've completed your purchase, and you can play them as often as you'd like.",
                "examplePhrases": [
                    "Alexa, play cave quest",
                    "Alexa, buy cave quest"
                ],
                "keywords": [
                    "Games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes 5 new adventures with Emerald and her friends.",
                    "boughtCardDescription": "Enjoy {PREMIUM_CONTENT_TITLE} by asking Alexa to play cave quest."
                }
            },
            "de-DE": {
                "name": "Cave Quest",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "  5 new adventures for your collection",
                "description": "The Cave Quest expansion pack includes 5 brand new adventures for your collection. Venture into even deeper and darker caves with Emerald and her friends, and collect up to 30 unique treasures. Adventures will automatically be playable once you've completed your purchase, and you can play them as often as you'd like.",
                "examplePhrases": [
                    "Alexa, play cave quest",
                    "Alexa, buy cave quest"
                ],
                "keywords": [
                    "Games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes 5 new adventures with Emerald and her friends.",
                    "boughtCardDescription": "Enjoy {PREMIUM_CONTENT_TITLE} by asking Alexa to play cave quest."
                }
            }
        },
        "distributionCountries": [ "AT", "DE", "LI", "LU", "US" ],
        "pricing": {
            "amazon.com": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.99,
                    "currency": "USD"
                }
            },
            "amazon.co.uk": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.54,
                    "currency": "GBP"
                }
            },
            "amazon.de": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.80,
                    "currency": "EUR"
                }
            }
        },
        "taxInformation": {
            "category": "SOFTWARE"
        }
    },
    "privacyAndCompliance": {
        "locales": {
            "en-US": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            },
            "en-GB": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            },
            "de-DE": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            }
        }
    },
    "testingInstructions": "Ask Alexa if she has any new adventures",
    "purchasableState": "PURCHASABLE",
    "promotableState": "ALL_AMAZON_CHANNELS"
}

Subscription product example

The following example shows a subscription product definition.

{
    "version": "1.0",
    "type": "SUBSCRIPTION",
    "referenceName": "treasure_finders_plus",
    "subscriptionInformation": {
        "subscriptionPaymentFrequency": "MONTHLY",
        "subscriptionTrialPeriodDays": 7
    },
    "publishingInformation": {
        "locales": {
            "en-US": {
                "name": "Treasure Finders Plus",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "1 new members-only adventure each month + over 10 previously released adventures.",
                "description": "Get access to a new adventure each month for members only, along with a growing collection of over 10 previously released members-only adventures. Includes Crystal Catchers, The Light Stone, The Dark Pool, The Cave Fish, Long Way Down and more.",
                "examplePhrases": [
                    "Alexa, open treasure finders plus",
                    "Alexa, play with treasure finders plus"
                ],
                "keywords": [
                    "Games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes access to all of our current adventures and a new one each month.",
                    "boughtCardDescription": "Enjoy {PREMIUM_CONTENT_TITLE}! Ask for a list of adventures to explore your purchase.."
                }
            },
            "en-GB": {
                "name": "Treasure Finders Plus",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "1 new members-only adventure each month + over 10 previously released adventures.",
                "description": "Get access to a new adventure each month for members only, along with a growing collection of over 10 previously released members-only adventures. Includes Crystal Catchers, The Light Stone, The Dark Pool, The Cave Fish, Long Way Down and more.",
                "examplePhrases": [
                    "Alexa, open treasure finders plus",
                    "Alexa, play with treasure finders plus"
                ],
                "keywords": [
                    "Games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes access to all of our current adventures and a new one each month.",
                    "boughtCardDescription": "Enjoy {PREMIUM_CONTENT_TITLE}! Ask for a list of adventures to explore your purchase.."
                }
            },
            "de-DE": {
                "name": "Treasure Finders Plus",
                "smallIconUri": "small-icon-uri",
                "largeIconUri": "large-icon-uri",
                "summary": "1 new members-only adventure each month + over 10 previously released adventures.",
                "description": "Get access to a new adventure each month for members only, along with a growing collection of over 10 previously released members-only adventures. Includes Crystal Catchers, The Light Stone, The Dark Pool, The Cave Fish, Long Way Down and more.",
                "examplePhrases": [
                    "Alexa, open treasure finders plus",
                    "Alexa, play with treasure finders plus"
                ],
                "keywords": [
                    "Games"
                ],
                "customProductPrompts": {
                    "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE} includes access to all of our current adventures and a new one each month.",
                    "boughtCardDescription": "Enjoy {PREMIUM_CONTENT_TITLE}! Ask for a list of adventures to explore your purchase.."
                }
            }
        },
        "distributionCountries": [ "AT", "DE", "LI", "LU", "US" ],
        "pricing": {
            "amazon.com": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.99,
                    "currency": "USD"
                }
            },
            "amazon.co.uk": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.54,
                    "currency": "GBP"
                }
            },
            "amazon.de": {
                "releaseDate": "2018-12-28T01:25Z",
                "defaultPriceListing": {
                    "price": 1.80,
                    "currency": "EUR"
                }
            }
        },
        "taxInformation": {
            "category": "SOFTWARE"
        }
    },
    "privacyAndCompliance": {
        "locales": {
            "en-US": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            },
            "en-GB": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            },
            "de-DE": {
                "privacyPolicyUrl": "url-to-privacy-policy"
            }
        }
    },
    "testingInstructions": "Sample testing instructions",
    "purchasableState": "PURCHASABLE",
    "promotableState": "ALL_AMAZON_CHANNELS"
}
Was this page helpful?

Last updated: Mar 26, 2024