Create and Manage In-Skill Products with the ASK CLI
To sell premium content in your skill, define one or more in-skill products and associate them with your skill. An in-skill product defines the type of purchase and details, such as pricing. You can use the Alexa Skills Kit (ASK) Command Line Interface (CLI) to add in-skill products to your skill.
- Prerequisites
- How managing products works
- To add a product and deploy it with the skill
- To modify a product
- To unlink and remove a product from a skill
- File structure for a skill that contains products
- Example product files
- Products list in a skill configuration file
- Related topics
Prerequisites
You must have 1.4.3 version or later of the ASK CLI installed. To get the latest version, follow the installation steps listed in the ASK CLI Quickstart.
How managing products works
Each product you create with the ASK CLI is represented by a JSON schema. This is stored in a file as described in File structure for a skill that contains products, later. You make changes to these local copies of your skill files. These changes take effect when you deploy the updated skill to your developer account.
The ASK CLI provides templates to create the appropriate schema for the type of in-skill product you create: subscription, entitlement (one-time purchase), consumable.
You can also manage your in-skill products in the developer console.
To add a product and deploy it with the skill
If you are in a directory for a skill you are managing with the ASK CLI, you can:
- Use the
add isp
command to add products to that skill using a template. For more options to add a skill, see theadd isp
command. - Use the
status
command with the--isp
flag to check the status of products. - Use the standard ASK CLI deploy command to deploy the skill.
Example
The following example shows the workflow to clone an existing skill, add a product, and then deploy that skill to the developer account.
$ ask clone
# Select an existing skill from the list to be cloned to the local workspace,
# and move to that directory.
$ cd my-existing-skill-name
# At the root directory of the ASK CLI skill project, run "ask add isp" to
# add an in-skill product.
$ ask add isp
? List of in-skill product types you can choose (Use arrow keys)
> Consumable
Entitlement
Subscription
# In this example, use arrow keys to select Entitlement
? List of in-skill product templates you can choose (Use arrow keys)
> Entitlement_Template
? Please type in your new in-skill product name:
(Entitlement_Template) cave_quest
In-skill product cave_quest is saved to .\isps\entitlement\cave_quest.json
$ cd isp/entitlement
# make some changes to the cave_quest.json file
$ ask status --isp
Purchasable in-skill product(s) to be deployed:
(Use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
(Use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)
DEPLOY STATUS | ID | FILE
Add | N/A | isps/entitlement/cave_quest.json
# Deploy the entire skill project to developer account including
# the in-skill products. During deployment, the in-skill product
# is associated to the current skill.
$ ask deploy
# Check status again
$ ask status --isp
Purchasable in-skill product(s) to be deployed:
(Use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
(Use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)
DEPLOY STATUS | ID | FILE
Update | amzn1.adg.product.0dc13545-bb0c-1... | isps/entitlement/cave_quest.json
# Note that the product ID shown in this example is truncated.
# status displays the full product ID in the format of:
# amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
To modify a product
You can update an existing product that is in development status by:
- Make a change in a local product file
- Deploy the skill with the updated file
Example
The following example shows the workflow to modify a product.
$ cd my-existing-skill-name
$ ask status --isp
Purchasable in-skill product(s) to be deployed:
(Use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
(Use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)
DEPLOY STATUS | ID | FILE
Update | amzn1.adg.product.0dc13545-bb0c-1... | isps/entitlement/cave_quest.json
# Open the product file and make some changes.
$ vim isps/entitlement/cave_quest.json
# Deploy the entire skill project to developer account including the in-skill products.
$ ask deploy
# Note that the product ID shown in this example is truncated.
# status displays the full product ID in the format of:
# amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
To unlink and remove a product from a skill
You can unlink a product associated with a skill with the ask remove isp
command. This disassociates the product from the skill and deletes the JSON file associated with the product. You can use this command on a product from a skill in the development stage, as long as the product has never been available in a live version of the skill.
- Use the
ask remove isp
command to set the product's deploy status to "Remove" - Use
ask status --isp
to confirm that the product will be removed in the deployment - Use
ask deploy
orask deploy --target isp
command to deploy the local changes to a developer account.
Note that before you remove a product, you may want to back up the file to another location for use later.
Example
The following example shows how to check the status of products for a skill, and then remove a product by file name.
$ cd my-existing-skill-name
# Use "ask status --isp" check what ISPs are associated with current skill.
# Products associated with the skill have a status of Update
$ ask status --isp
Purchasable in-skill product(s) to be deployed:
(Use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
(Use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)
DEPLOY STATUS | ID | FILE
Update | amzn1.adg.product.0dc13545-bb0c-1... | isps/entitlement/cave_quest.json
Update | amzn1.adg.product.0dc13545-bb0c-2... | isps/subscription/treasure_finders.json
# At the root directory of the ASK CLI skill project, use the
# remove command.
$ ask remove isp --file isps/entitlement/cave_quest.json
# Check the status again to see the status is remove.
$ ask status --isp
Purchasable in-skill product(s) to be deployed:
(Use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
(Use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)
DEPLOY STATUS | ID | FILE
Remove | amzn1.adg.product.0dc13545-bb0c-111-11 | isps/entitlement/cave_quest.json
Update | amzn1.adg.product.92fef67c-2da3-111-11 | isps/subscription/treasure_finders.json
# Deploy the changes.
$ ask deploy --target isp
$ ask status --isp
Purchasable in-skill product(s) to be deployed:
(Use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
(Use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)
DEPLOY STATUS | ID | FILE
Update | amzn1.adg.product.92fef67c-2da3-111-11 | isps/subscription/treasure_finders.json
# Note that the product ID shown in this example is truncated.
# status displays the full product ID in the format of:
# amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
File structure for a skill that contains products
When you use the add isp
command, an isps
folder is added to your skill project, and the consumable
, entitlement
, and/or subscription
subfolders are added.
The consumable
, entitlement
, and/or subscription
folder contains a product description file (*ispName*.json
) for each product.
The following shows an example of how the skill project looks when products are added.
skillName
│ skill.json
├───.ask
│ config
│
├───isps
│ │
│ ├───consumable
│ │ ispName1.json
│ │
│ ├───entitlement
│ │ ispName2.json
│ │
│ └───subscription
│ ispName3.json
│
├───lambda
│ └───custom
│ │ index.js
│
└───models
en-US.json
Example product files
For examples of the product JSON files, see:
Since these files are created from a template, you must modify the publishingInformation
, keywords
, customProductPrompts
, smallIconUri
, largeIconUri
, boughtCardDescription
, pricing
objects, and more for your products. For more details about what these fields mean, see product schema parts.
Products list in a skill configuration file
When a skill has an associated product, the configuration file for the skill (.ask/config
) contains a in_skill_products
list that contains the product IDs, the file location for the products, and their status. Following is an example.
{
"deploy_settings": {
"default": {
"skill_id": "amzn1.ask.skill.b1845aa7-0fac-1234-1111-5f1f478ca",
"was_cloned": false,
"merge": {
"manifest": {
"apis": {
"custom": {
"endpoint": {
"uri": "ask-some-endpoint-profile"
}
}
}
}
},
"in_skill_products": [
{
"productId": "amzn1.adg.product.0dc13545-bb0c-111-11",
"filePath": "isps/entitlement/cave_quest.json",
"deploy_status": "Update",
"eTag": "tag_1"
},
{
"productId": "amzn1.adg.product.0dc13545-bb0c-222-22",
"filePath": "isps/subscription/treasure_finders.json",
"deploy_status": "Update",
"eTag": "tag_2"
},
{
"productId": "amzn1.adg.product.0dc13545-bb0c-333-33",
"filePath": "isps/consumable/clues.json",
"deploy_status": "Update",
"eTag": "tag_3"
}
]
}
}
}