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

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 the add 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

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 or ask 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"
        }
      ]
    }
  }
}