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

To create in-skill products, you must create a custom skill in a locale that supports in-skill purchasing. For available locales, see Languages and locales that support in-skill products.

You must have version 2 or later of the ASK CLI. To get the latest version, follow the installation steps listed in the ASK CLI Quickstart.

Familiarize yourself with the JSON schema definitions for each of the in-skill product payment models: One-Time Purchase, Subscription, and Consumable. To define your products, modify the schema with your product information. For details, see product schema parts. You define your products in a JSON file.

CLI command summary for in-skill products

You can use the following CLI commands to manage your in-skill products:

• associate-isp-with-skill — Link an existing product to the skill.
• create-isp-for-vendor — Create a new product associated with the vendor ID of your Amazon developer account.
• delete-isp-for-product — Delete the product with the given product ID. Only supported for products in the development stage.
• disassociate-isp-with-skill — Unlink the specified product from the skill.
• get-isp-associated-skills — Get the list of products linked to the skill.
• get-isp-definition — Get the definition of the specified product ID.
• get-isp-list-for-skill-id — Get the list of products linked to the skill.
• get-isp-list-for-vendor — Get the list of products created by the vendor ID associated with your Amazon developer account.
• get-isp-summary — Get the summary information for a specified product ID.
• update-isp-for-product — Update the product definition for a specified product ID.

View the in-skill products for a skill

Use the get-isp-list-for-vendor command to list all the products that you created with your Amazon developer account. To list the products associated with your skill, use ask smapi get-isp-list-for-skill-id --skill-id <skill-id>.

The following example shows the CLI command to get the list of all products that the developer created with their account.

$ cd my-existing-skill-name

$ ask smapi get-isp-list-for-vendor
{
    "_links": {
        "next": {
            "href": "/v1/inSkillProducts?vendorId=MMMMMRZ"
        },
        "self": {
            "href": "/v1/inSkillProducts?vendorId=MMMMMRZ"
        }
    },
    "inSkillProductSummaryList": [{
            "editableState": "EDITABLE",
            "lastUpdated": "2021-02-26T18:18:41.275Z",
            "nameByLocale": {
                "en-US": "my fun subscription"
            },
            "pricing": {
                "amazon.co.jp": {
                    "defaultPriceListing": {
                        "currency": "JPY",
                        "price": 99,
                        "primeMemberPrice": 79.2
                    },
                    "releaseDate": "2021-02-26T00:00:00Z"
                },
                "amazon.com": {
                    "defaultPriceListing": {
                        "currency": "USD",
                        "price": 0.99,
                        "primeMemberPrice": 0.8
                    },
                    "releaseDate": "2021-02-09T00:00:00Z"
                }
            },
            "productId": "amzn1.adg.product.39e08b9f-8699-4988-b859-10173cf31d82",
            "promotableState": "IN_SKILL_ONLY",
            "purchasableState": "PURCHASABLE",
            "referenceName": "testSubscription",
            "stage": "development",
            "status": "COMPLETE",
            "type": "SUBSCRIPTION"
        },
        {
            "editableState": "EDITABLE",
            "lastUpdated": "2022-02-15T20:29:23.220Z",
            "nameByLocale": {},
            "pricing": {
                "amazon.com": {
                    "defaultPriceListing": {
                        "currency": "USD",
                        "price": 0.99,
                        "primeMemberPrice": 0.8
                    },
                    "releaseDate": "2021-02-15T00:00:00Z"
                },
                "amazon.it": {
                    "defaultPriceListing": {
                        "currency": "EUR",
                        "price": 0.99,
                        "primeMemberPrice": 0.8
                    },
                    "releaseDate": "2022-02-15T00:00:00Z"
                }
            },
            "productId": "amzn1.adg.product.c376ccf7-8c27-40eb-919c-0686a5bdd074",
            "promotableState": "IN_SKILL_ONLY",
            "purchasableState": "PURCHASABLE",
            "referenceName": "AddConsumableProduct",
            "stage": "development",
            "status": "INCOMPLETE",
            "type": "CONSUMABLE"
        },
        {
            "editableState": "EDITABLE",
            "lastUpdated": "2021-07-07T19:31:19.074Z",
            "nameByLocale": {
                "en-US": "5GoldCoins"
            },
            "pricing": {
                "amazon.com": {
                    "defaultPriceListing": {
                        "currency": "USD",
                        "price": 0.99,
                        "primeMemberPrice": 0.80
                    },
                    "releaseDate": "2021-02-15T00:00:00Z"
                }
            },
            "productId": "amzn1.adg.product.8761329b-7d48-44ba-9425-b28fc30b3f5a",
            "promotableState": "IN_SKILL_ONLY",
            "purchasableState": "PURCHASABLE",
            "referenceName": "testOneTimePurchase",
            "stage": "development",
            "status": "COMPLETE",
            "type": "ENTITLEMENT"
        }
    ],
    "isTruncated": false
}

Create in-skill products and link to your skill

To create a new in-skill product, create a JSON file with one or more product definitions. The product definition includes your vendor ID and the ISP schema for the payment model. To create the product, use the create-isp-for-vendor command. To link the product to your skill, use the associate-isp-with-skill command. After you link the product with your skill, update your skill code for the new product. For details about the contents of the JSON file, see Create a new in-skill product request body.

The following example shows the CLI commands to create a product, link it to a skill, and then get the list of products associated with the skill.

Update in-skill products

To modify an existing product in the development stage, update your product definition JSON file. The product definition includes your vendor ID and the ISP schema for the payment model. To modify the product, you use the update-isp-for-product command. For details about the contents of the JSON file, see Create a new in-skill product request body.

The following example shows the CLI command to modify an existing product.

Delete a product

You can delete 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. Before you remove a product, you might want to back up the file to another location for use later.

The following example shows how to delete the product by product ID.

Discontinue a product in a live skill

After a product is live, discontinuing that product can cause a negative experience for the customer. To avoid discontinuing a product, design your premium products according to best practices . If you do have a strong reason to discontinue a live product, you can disassociate the product from the skill. This change requires you to submit the skill for recertification. Consider this decision carefully and avoid any changes that break the experience for your existing customers.

Discontinuing a product has the following affects:

• Customers can no longer purchase the product.
• For a consumable or one-time purchase, existing customers who purchased the product continue to have access to it. Your skill should continue to support these users.
• For a subscription, existing customers who subscribed continue to have access to the product for the remainder of the subscription term. The subscription doesn't automatically renew at the end of the term.

After you publish your skill, the status of the skill changes to Live and a new development version is automatically created. The development version has the same information as the original live version. Use the development version to discontinue an in-skill product.

The following example shows how to unlink a product from a skill.

Skill package file structure for in-skill products

When your skill package contains in-skill products, those products associated with your skill are defined in the skill package in the folder named, isps. This folder contains one or more product definition files and a file named, isps.json, that describes the products to link to your skill.

The following example shows a skill package with two products named, product1.json and product2.json.

SkillPackageName.zip
├── assets
├── interactionModels
├── isps
│   ├── isps.json
│   ├── product1.json
│   └── exampleDirectory
│       └── product2.json
└── skill.json

The isps.json file has two sections: the products to create or update and existing products to associate with the skill. Each product definition file that you create follows the ISP JSON schema format.

The following example shows the contents of the isps.json file with two new products to create and two existing products to associate with the skill.

The following table describes each object in the isps.json file:

Property	Description
isps	List of one or more products, each with a unique reference name, that you want to create or update. Each product contains a path that specifies the location of the ISP schema file relative to the skill package root file, skill.json file. You can organize the product files in any directory structure that you want. Valid values for reference name: alphanumeric characters and underscores"
associations	List of existing products to link to your skill. Each product is identified with a product ID that Amazon generated when it created the product. To get the product ID, use the In-Skill Product Management API, ASK CLI or the developer console.

Related topics

• ASK CLI Command Reference
• Add ISP Support to Your Skill Code
• Design a Good Customer Experience for In-Skill Purchasing
• In-Skill Purchase Testing Guide
• Skill Package Management REST API