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
Deactivated products

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

<locale>

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.

<locale>.name

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.

<locale>.summary

Summary description of the product.

String from 1-160 characters, inclusive.

<locale>.description

A full description explaining the product's functionality and any prerequisites to using it.

String 1-4000 characters, inclusive.

<locale>.smallIconUri

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 file://assets/images/isp1/en-US_smallIcon.png.

Properly formatted URI string

<locale>.largeIconUri

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 file://assets/images/isp1/en-US_largeIcon.png.

Properly formatted URI string

<locale>.examplePhrases

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.

<locale>.keywords

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.

<locale>.customProductPrompts

An object that contains prompts and descriptions for this product for this locale.

customProductPrompts object

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:
  • Include the product name. Use "`{PREMIUM_CONTENT_TITLE}`" as a token for the name field. Do not use "{" or "}" anywhere else in the prompt.
  • Include what is unique about this product
  • Be as brief as possible
  • NOT include any pricing information, as Amazon automatically appends the price in the purchase flow.
  • Avoid repeating the same phrases customers may have heard in the previous step

 String between 1 and 160 characters long that optionally contains the placeholder {PREMIUM_CONTENT_TITLE}.
boughtCardDescriptionA 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

<marketplace>

Describes where the product is offered for sale.

String. For valid values, see Marketplaces that support in-skill products.

<marketplace>.releaseDate

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.

<marketplace>.defaultPriceListing

The default list price and currency assigned to the product for this marketplace.

Object

defaultPriceListing.price

List price for the product.

A number (long). For minimum and maximum price values, see Price ranges for in-skill products.

defaultPriceListing.currency

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.

Back to product schema parts

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

<locale>

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.

<locale>.privacyPolicyUrl

A URL to the privacy policy for this locale.

Properly formatted URL string

Back to product schema parts

Last updated: Sep 30, 2022