In-Skill Purchasing Schemas
This topic contains examples of the in-skill product schemas and descriptions of the schema parts.
Subscription Schema
The following is an example of a subscription product schema.
{
"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", "IE", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "FI", "GB", "GG", "GI", "GR", "HR", "HU", "LT", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "UA", "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"
}
Entitlement Schema
The following is an example of an entitlement product schema.
{
"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", "IE", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "FI", "GB", "GG", "GI", "GR", "HR", "HU", "LT", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "UA", "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"
}
Consumable Schema
The following is an example of a consumable product schema.
{
"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", "IE", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "FI", "GB", "GG", "GI", "GR", "HR", "HU", "LT", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "UA", "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": "Start a game. When asked a question, ask Alexa for a hint.",
"purchasableState": "PURCHASABLE",
"promotableState": "ALL_AMAZON_CHANNELS"
}
Product schema parts
Following are descriptions of the in-skill product schema parts.
Product object
A product contains the following fields.
Field | Description | Type |
---|---|---|
version |
The version indicator. | String. Valid value: 1.0 |
type |
The type of in-skill product. | String. Valid values: CONSUMABLE , ENTITLEMENT , SUBSCRIPTION |
referenceName |
The canonical name of the in-skill product. This name is used when referring to the product in code. | String 3-50 characters long, with no spaces. |
publishingInformation |
An object that contains information about how the product is presented to end users, by locale. | publishingInformation object |
privacyAndCompliance |
An object provides privacy policy URLs by locale. | privacyAndCompliance object |
testingInstructions |
Testing instructions such as test account credentials. | String 1-4000 characters, inclusive. |
promotableState |
Indicates whether you want the product to be available for in-skill purchases only or on all channels. Availability on all channels means it will be available for in-skill purchasing as well as on Amazon.com. Availability on all channels is the default. | String enumeration value: IN_SKILL_ONLY or ALL_AMAZON_CHANNELS |
purchasableState |
Indicates whether the product is purchasable. See Deactivated products, later, for more about products that cannot be purchased. | String enumeration value: PURCHASABLE or NOT_PURCHASABLE |
subscriptionInformaton |
Required for subscriptions only. Describes the billing frequency and trial period length for the subscription. | SubscriptionInformation Object |
When
purchasableState
is NOT_PURCHASABLE
, the product is considered deactivated. In a live skill, customers can no longer purchase the product. However, customers who previously purchased and are entitled to it continue to have access to the product, so your skill should continue to support these users. For a subscription, the existing customers continue to have access to the product for the remainder of the subscription term. A deactivated subscription does not automatically renew.SubscriptionInformation object
Required for subscriptions only. Describes the billing frequency and trial period length for the subscription.
Field | Description | Type |
---|---|---|
subscriptionPaymentFrequency |
Required for subscriptions only. Indicates how often the customer is billed for the subscription. | String. Valid values: MONTHLY, YEARLY |
subscriptionTrialPeriodDays |
Required for subscriptions only. Indicates the duration of the trial period, in days. | Integer between 0 and 90, inclusive. |
PublishingInformation object for an in-skill product
A publishingInformation
object contains the following fields.
Field | Description | Type |
---|---|---|
locales |
A map of locale objects that provide specific information for each supported locale. | Object that contains a map of locale objects. |
distributionCountries |
List specifying distribution country/region strings in ISO 3166-1 alpha-2 format. | String list. For valid values, see Countries and regions that support in-skill products. |
pricing |
Contains details about pricing of the product. | pricing object |
taxInformation |
Provides the tax information for the product. | Object |
taxInformation.category |
The tax category for the product. | String. Valid values: INFORMATION_SERVICES, NEWSPAPERS, PERIODICALS, SOFTWARE, STREAMING_RADIO, VIDEO. For more about the meaning of these categories, see Tax category field (developer console). |
Publishing information locale
Each publishingInformation
object contains a map of locale objects that describe publishing information specific to that locale. Each locale is identified with a 2-letter language code, a hyphen followed by the 2-letter country/region code.
Field | Description | Type |
---|---|---|
|
2-letter language code, a hyphen followed by the 2-letter country/region code. |
String. For valid values, see Locales that support in-skill products. |
|
The name for the product for this locale. This name is included in purchase confirmation prompts, Alexa app purchasing cards and email receipts. |
String 2-50 characters, inclusive. |
|
Summary description of the product. |
String from 1-160 characters, inclusive. |
|
A full description explaining the product's functionality and any prerequisites to using it. |
String 1-4000 characters, inclusive. |
|
A URI to a 108px x 108px PNG with transparency, which represents the in-skill product. Because the image is rounded when displayed, it is recommended that the image has 75px padding on all sides. You can reuse the small icon associated with your skill, or provide a unique image to represent your in-skill product. This value can be a publicly-accessible URL or, when using the skill package format, a path relative to the skill package's skill.json file, such as |
Properly formatted URI string |
|
A URI to a 512px X 512px PNG with transparency, which represents the in-skill product. Because the image is rounded when displayed, it is recommended that the image has 75px padding on all sides. You can reuse the large icon associated with your skill, or provide a unique image to represent your in-skill product. This value can be a publicly-accessible URL or, when using the skill package format, a path relative to the skill package's skill.json file, such as |
Properly formatted URI string |
|
List of example phrases that illustrate how users can ask for your product. These phrases must be supported in your voice model. |
String list that contains 1-3 entries. Each string in the list can be 2-200 character, inclusive. |
|
Keyword phrases that describe the product offering. |
String list that contains 1-30 entries. Each string in the list should be 1-150 characters, inclusive. |
|
An object that contains prompts and descriptions for this product for this locale. |
customProductPrompts object
A customProductPrompts
object contains two fields that provide descriptions of your product when a customer makes a purchase. These should be in the language of of the specified locale.
Field | Description | Type |
---|---|---|
purchasePromptDescription |
The description of the product a customer hears when they make a purchase or cancel a subscription. A purchasePromptDescription should:
|
String between 1 and 160 characters long that optionally contains the placeholder {PREMIUM_CONTENT_TITLE}. |
boughtCardDescription | A description of the product that displays on the skill card in the Alexa app. | String between 1-160 characters, inclusive that optionally contains the placeholder {PREMIUM_CONTENT_TITLE}. |
pricing object
A pricing object contains a map of marketplace objects, which contain details about pricing in that marketplace.
Field | Description | Type |
---|---|---|
|
Describes where the product is offered for sale. |
String. For valid values, see Marketplaces that support in-skill products. |
|
Future UTC date that indicates when the product releases. Note that this date cannot be changed once a skill is published live, regardless of the date specified. |
Date/time string in ISO 8601 format. For example, yyyy-MM-dd'T'HH:mm'Z' or yyyy-MM-dd. |
|
The default list price and currency assigned to the product for this marketplace. |
Object |
|
List price for the product. |
A number (long). For minimum and maximum price values, see Price ranges for in-skill products. |
|
The ISO 4217- 3 digit alpha code that indicates the currency of the specified list price. |
String. For available currencies, see Price ranges for in-skill products. |
privacyAndCompliance object
A privacyAndCompliance
object contains a map of locale objects, which in turn contains privacy information specific to that locale. Each locale is identified with a 2-letter language code, a hyphen followed by the 2-letter country/region code. Each locale identified in the publishingInformation object must have an entry in this map, and a valid privacyPolicyUrl
for the locale.
Field | Description | Type |
---|---|---|
|
A language tag that contains the 2-letter language code, a hyphen followed by the 2-letter country/region code. |
String. For valid values, see Locales that support in-skill products. |
|
A URL to the privacy policy for this locale. |
Properly formatted URL string |
Last updated: Sep 30, 2022