Use the ASK CLI to Manage In-Skill Products

Adding in-skill products (ISPs) to a skill is easy using the Alexa Skills Kit Command Line Interface (ASK CLI). This topic will help you get started with creating and managing in-skill products.

Product types

There are two different types of in-skill products that you can add and manage with the ASK CLI.

  • One-time purchases: Entitlements that unlock access to features or content within a skill. Entitlements do not expire.
  • Subscriptions: Offers access to premium content or features for a period of time. Users are charged on a recurring basis until they cancel their subscription.

Use the product templates and high-level commands to add and manage entitlements and subscriptions for your Alexa skills.

Prerequisites

You must have 1.3.0 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

When you manage products with the ASK CLI you will make changes in local copies of your skill files. These changes take effect when you deploy the updated skill to your developer account.

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

# Execute command "ask add isp" at the root directory of the ASK CLI skill
# project to add an in-skill product.

$ ask add isp 

? List of in-skill product types you can chose (Use arrow keys)
❯ Entitlement 
  Subscription 

? List of in-skill product templates you can chose (Use arrow keys)
❯ Entitlement_Base

? List of in-skill product templates you can chose Entitlement_Base
? Please type in your new in-skill product name:
 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 


$ 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-111-11  | isps/entitlement/cave_quest.json 

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-111-11  | 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 

To remove a product

You can remove a product associated with a skill by:

  • 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-111-11  | isps/entitlement/cave_quest.json 
Update        | amzn1.adg.product.92fef67c-2da3-111-11  | 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

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 entitlement and/or subscription subfolders are added. The entitlement and/or subscription folder contains the product description file ispName.json.

The following shows an example of how the skill project looks when products are added.

-skillName
   -.ask
      -config
   -lambda
      -custom
        -index.js
   -models
      -en-US.json
   -skill.json
   -isps
    -entitlement
      -ispName1.json
    -subscription
      -ispName2.json

Example product files

See the Entitlement Schema or the Subscription Schema for examples of the product JSON files. 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": {
        "skillManifest": {
          "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-111-11",
          "filePath": "isps/subscription/treasure_finders.json",
          "deploy_status": "Update",
          "eTag": "tag_2"
        }
      ]
    }
  }
}
Topic Description
Command Reference for In-Skill Products CLI high and low-level commands for managing in-skill products.
In-Skill Product Schemas Product schemas and descriptions of the schema parts.