Skill Rollback

The skill rollback feature reverts your skill to a previous live version without having to resubmit the skill for manual recertification. This process helps you move between development cycles. For example, you might choose to rollback a skill if your new skill version introduced a bug or any other unintended behaviors.

You rollback a skill by using the Alexa Skills Kit (ASK) Command Line Interface (CLI).

Skill rollback eligibility criteria

The skill rollback eligibility ensures that your skill adheres to Amazon policy testing requirements and won't cause problems if it's rolled back.

The following list might not be exhaustive, depending on the specific features you support. In all cases, skills must also pass Amazon’s certification criteria, including adhering to Amazon’s content guidelines. For more details on these content guidelines, see Policy Testing for an Alexa Skill. Note that skills that use certain features aren't eligible for rollback. For example, skills that support Account Linking aren't eligible for rollback.

To check if your skill is eligible for rollback

  • Only custom skills and music skills are eligible.
  • Your skill development cycle uses versions. For more details, see skill versioning.
  • The previous skill you are reverting to passed certification within the last six months.
  • The previous skill you are reverting to isn't suppressed, rejected, withdrawn.
  • Your skill didn't add any new locales between versions.
  • Your skill didn't add In-Skill Purchasing (ISP) or Account Linking between versions.
  • Your skill didn't change it's invocation name between versions.
  • Your skill didn't change from a child directed skill to a non child directed skill between versions.

Skill versioning

Skill versioning captures a snapshot of your skill and each of its sub-resources when it's submitted for review. You can add a version message and manage the different skills that you publish by viewing the history of your skill versions. To help identify a skill version, you provide a version comment with every submission of your skill. You can then use this comment along with the submission time to orient yourself to the appropriate version.

The skill rollback feature depends on skill versioning. Tracking the versions of a skill allows you to accurately rollback to the appropriate snapshot. To add a version message to your skill, use the submit-skill-for-certification CLI command or the developer console.

Frequently asked questions

What types of skills support rollback?

Skill rollback supports custom skills and music skills. All skills must meet the minimum eligibility criteria.

What skill assets rollback with this feature?

Rollback works on the skill level, not the skill resource level. The following assets rollback: Manifest data and Interaction Model. Amazon owned artifacts – for example, built-in intents and slots, formatters and tokenizers – are not rolled back to their older version.

Does a rollback change a skill that's still in development?

No, skill rollback doesn't make any changes to a skill that's in the development stage.

Use the developer console

The developer console only supports submitting an optional version message to your skill. It doesn't support rollback.

Submit a version message

To submit a skill for certification and add an optional version message

  1. Sign in to the ASK developer console.
  2. Select the Certification tab for the skill that's ready for review.
  3. Select the Submission tab.
  4. Enter a version message in the Version message box.
  5. Click Submit for review.

CLI version commands

Use the following CLI commands to version your skill.

submit-skill-for-certification

Submit a skill for certification and add a version message.

Syntax:

ask smapi submit-skill-for-certification [-s,--skill-id <skill-id>]
                                         [--publication-method <publication-method>]
                                         [--version-message <version-message>]
                                         [-p, --profile <profile>]
                                         [--debug]
                                         [-h, --help]

Options:

-s, --skill-id <skill-id>
Required. The skill ID.
--publication-method <publication-method>
Optional. Determines how a skill publishes after it's certified. Accepted values: MANUAL_PUBLISHING,AUTO_PUBLISHING.

If you omit this value, the skill defaults to AUTO_PUBLISHING.
–version-message <version-message>
Optional. Description of the version. Max 300 characters.
--debug
Optional. When you include this option, ASK CLI displays debug messages in the output of the command.

list-versions-for-skill

Retrieve a list of all skill versions associated with a skill id.

Syntax:

ask smapi list-versions-for-skill [-s,--skill-id <skill-id>]
                                  [--next-token <next-token>]
                                  [--max-results <max-results>]
                                  [-p, --profile <profile>]
                                  [--debug]
                                  [-h, --help]

Options:

-s, --skill-id <skill-id>
Required. The skill ID.
--next-token <next-token>
Optional. Continuation token to control MaxResults pagination.
--max-results <max-results>
Optional. Sets the maximum number of results returned in the response body. You can't exceed 50 results. If there are more than 50 results displayed, the response includes isTruncated = true.
--debug
Optional. When you include this option, ASK CLI displays debug messages in the output of the command.

CLI rollback commands

Use the following CLI commands to use the skill rollback feature.

rollback-skill

Submit a target skill version to rollback to. Only one rollback or publish operation can occur at a time for a given skillId. Your skill must meet the rollback eligibility requirements.

Syntax:

ask smapi rollback-skill [-s,--skill-id <skill-id>]
                         [--target-version <target-version>]
                         [-p, --profile <profile>]
                         [--debug]
                         [-h, --help]

Options:

-s, --skill-id <skill-id>
Required. The skill ID.
--target-version <target-version>
Required. The identifier for a rollback request.
-p, --profile <profile>
Optional. The profile under which ASK CLI deploys the skill resources. If not provided, ASK CLI uses the default profile.
--debug
Optional. When you include this option, ASK CLI displays debug messages in the output of the command.

get-rollback-for-skill

Get the rollback status of a skill given an associated rollbackRequestId. Use ~latest in place of rollbackRequestId to get the latest rollback status.

Syntax:

ask smapi get-rollback-for-skill [-s,--skill-id <skill-id>]
                                 [--rollback-request-id <rollback-request-id>]
                                 [-p, --profile <profile>]
                                 [--debug]
                                 [-h, --help]

Options:

-s, --skill-id <skill-id>
Required. The skill ID.
--rollback-request-id <rollback-request-id>
Required. The identifier for a rollback request. If set to ~latest, the request returns the status of the latest rollback request.
-p, --profile <profile>
Optional. The profile under which ASK CLI deploys the skill resources. If not provided, ASK CLI uses the default profile.
--debug
Optional. When you include this option, ASK CLI displays debug messages in the output of the command.

Versioning API references

The skill versioning CLI commands interface with the following APIs.

Submit version message

Adds a version message to your skill submission. Use the Location header to track the status of this request.

Request

The endpoint of the API is https://api.amazonalexa.com. Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.

POST /v1/skills/{skillId}/submit

Parameters

Field Description Parameter Type Required?
versionMessage A custom message that identifies your skill version. Max 300 characters. String No

Response

HTTP/1.1 200 OK

Response fields

Field Description Parameter Type
Location Returns a relative URL to track the progress of the clone workflow. String

List skill versions

Returns a list of all skill versions. Only applies to certified skills.

Request

The endpoint of the API is https://api.amazonalexa.com. Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.

GET /v1/skills/{skillId}/versions
Field Description Parameter Type Required
skillId The unique identifier of the skill. Object Yes
MaxResults Maximum number of results to display per page of listed skills. Max number of returned results can't exceed 50. Query parameter No
nextToken Continuation token to control MaxResults pagination. Query parameter No

Response

The following example illustrates the structure of the response body.

{
  "_links": {
    "self": {
      "href": "/v1/skills/amzn1.ask.skill.04430552-6fdb-4a59-8588-93171d79fbb0/versions"
    }
  },
  "isTruncated": false,
  "skillVersions": [
    {
      "creationTime": "Wed Jul 01 23:20:11 UTC 2020",
      "message": "Updating the skill icon, and description message.",
      "submissions": [
        {
          "status": "LIVE",
          "submissionTime": "Wed Jul 01 23:20:11 UTC 2020"
        }
      ],
      "version": "2"
    },
    {
      "creationTime": "Wed Jul 01 22:46:16 UTC 2020",
      "message": "Initial submission, excited to try this new feature.",
      "submissions": [
        {
          "status": "CERTIFIED",
          "submissionTime": "Wed Jul 01 22:46:16 UTC 2020"
        }
      ],
      "version": "1"
    }
  ]
}

Response parameters

Field Description Parameter Type
skillVersions.version The skill version number. String
skillVersions.message Custom message to track skill versions. String
skillVersions.creationTime When the skill was submitted for certification and a version was created. String
skillVersions.submissions An object containing information about submission status. String
skillVersions.submissions.status The status of a submission. String
skillVersions.submissions.submissionTime The date and time of a version submission. String

Submission status

Field Description
LIVE The skill version is in the live stage.
CERTIFIED The certified skill version.
IN_REVIEW The skill version is in review for certification and publication. During this time, you can't edit the configuration.
FAILED CERTIFICATION The skill version failed the certification review. Submit a new version for certification.
HIDDEN You published your skill version, but it's no longer available to new users for activation. Existing users can still invoke this skill if it's the most recent version.
REMOVED You published your skill version, but it's removed due to a policy violation. You can update your skill and publish a new live version to address the policy violation.
WITHDRAWN_FROM_CERTIFICATION The skill version was withdrawn from review.

Rollback API references

The skill rollback CLI commands interface with the following APIs.

Rollback a skill

Submit a target skill version to rollback to. Only one rollback or publish operation can occur at a time for a given skillId. Your skill must meet the rollback eligibility requirements.

Request

The endpoint of the API is https://api.amazonalexa.com. Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.

POST /v1/skills/{skillId}/rollbacks

Request parameters

Field Description Parameter Type Required?
skillId The unique identifier of the skill. Path Yes

Request body structure

The following example shows the structure of the response body.

{
  targetVersion : "{{STRING}}"  
}

Request parameters

Field Description Parameter Type Required?
targetVersion The targeted skill version you are rolling back to. String Yes

Get rollback status

Get the rollback status of a skill given an associated rollbackRequestId.

Request

The endpoint of the API is https://api.amazonalexa.com. Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.

GET /v1/skills/{skillId}/rollbacks/{rollbackRequestId}

Request parameters

Field Description Parameter Type Required?
skillId The unique identifier of the skill. Object Yes
rollbackRequestId The unique identifier for a rollback workflow. String Yes

Response

201 Created
{
  "rollbackRequestId": "93990bd2-afc9-48a8-94d6-862ce5db5ca5"
}

Response body structure

The following example illustrates the structure of the response body.

{
  "id": "727cb65c-ef40-4c02-873f-262f4b60a0bf",
  "status": "IN_PROGRESS",
  "submissionTime": "Sat Jun 27 01:24:01 UTC 2020",
  "targetVersion": "1"
  "errors" : [
         {
             "code": ""
             "validationDetails" : {}
             "message": ""
         }
   ]   
}

Response fields

Field Description Parameter Type
targetVersion The targeted skill version you are rolling back to. String
submissionTime The date and time for a submitted version. String
id The unique identifier of the rollback request. String
status Status of a rollback request. String
errors An object containing information about rollback errors. List
errors.code List of standardized error codes. List
errors.validationDetails Details about error validation. List
errors.message Details about the error. String

Error codes

Error Code Description
2XX Success. The skill rollback operation started.
4XX Validation error. An error occurred before the rollback operation started.
5XX System error. An error occurred before the rollback operation started.
HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict with the target resource
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable