Alexa Shopping Actions API Reference

To add a shopping experience to your skill, use the Alexa Shopping Actions API to recommend products from the Amazon retail website. Your skill uses skill connections to invoke Amazon predefined tasks to start the Alexa shopping interaction. Skill connections enable a skill to use another skill to perform a specific task. Before you use the Alexa Shopping Actions API, review the following topics:

For examples of how to implement the API in your skill, see Implement Alexa Shopping Actions in Your Skill.

Shopping actions

The Alexa Shopping actions include the following tasks.

Shopping action Task name and version

Add to list

connection://AMAZON.AddToList/1

Add to shopping cart

connection://AMAZON.AddToShoppingCart/1

Buy products

connection://AMAZON.BuyShoppingProducts/1

Recommend products

connection://AMAZON.RecommendShoppingProducts/1

Add to list

Add the specified items to the customer's Amazon Wish List. At this time, the action works for the Wish List only, not for the Amazon Shopping List.

Request

To add products to the customer's Wish List, add a Connections.StartConnection directive to your response.

Request example

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.AddToList/1",
  "input": {
    "products": [
      {
        "asin": "ASIN1"
      }
  ],
  "listType": "WISHLIST"
  },
  "token": "Skill-specific session information"
}

Request parameters

The following table shows the definition of the task-specific input parameter.

Field Description Type Required

input

Input parameters for the task request.

Object

Yes

input.products

List of Amazon products.
Maximum items: 1.

Array of ProductEntity objects

Yes

input.products[].asin

Amazon system identifier for a product. For details, see ASIN for a product.

String

Yes

input.listType

Identifies the list type.
Valid value: WISHLIST

String

Yes

Response

The task returns a SessionResumedRequest response that contains the result of the action. To determine if the action succeeded, check the cause.status and task-specific cause.result parameters. The cause.status parameter includes an HTTP status code. For a list of status codes, see Status code attributes in SessionResumedRequest.

Response example

The following example shows a successful response.

{
    "type": "SessionResumedRequest",
    "requestId": "Unique id for the request",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "en-US",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "Skill-specific session information to restore the skill session",
        "status": {
            "code": "200",
            "message": "OK"
        }
    }
}

Response parameters

The following table shows the definition of the task-specific result parameter. The result parameter is optional. For details about the return values, see Result codes.

Field Description Type Required

code

Identifies the error.

String

Yes

message

Human-readable description of the error.

String

Yes

Result codes

Code Message Description

AlexaShopping.InternalError

We're unable to process your request at this time. Please retry your request. If you encounter this error repeatedly, please reach out to Customer Support.

Internal problem or outage prevented Alexa Shopping from completing your request.

AlexaShopping.InvalidTaskForMarketplace

This operation is not available for this locale.

Requested Alexa Shopping action isn't supported in this locale.

AlexaShopping.ItemNotEligible

The item you specified is not eligible for Alexa Shopping Actions.
Or, the item is not accessible through Alexa Shopping.

Indicates that the item isn't eligible for use with Alexa Shopping.
For example, the item is digital or the item isn't supported for legal reasons.

AlexaShopping.NoOffersFound

We did not find any matches for your request.

Request item wasn't found. For example, the item is out of stock.

AlexaShopping.RetryLaterError

We encountered an error when trying to process the request, please try again later.

Issue occurred while executing the task. For example, the customer has invalid settings or Alexa Shopping had a temporary issue.
The issue is recoverable. Try again later.

Add to shopping cart

Add the specified items to the customer's Amazon Shopping Cart. This action works for non-digital products only. For details, see the Alexa Shopping Actions for Alexa Skills FAQ.

Request

To add products to the customer's shopping cart, add a Connections.StartConnection directive to your response.

Request example

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.AddToShoppingCart/1",
  "input": {
    "products": [
      {
        "asin": "ASIN1",
        "attribution": {
            "associateId": "some.associate.id",
            "trackingId": "some.tracking.id"
        }
      }
    ]
  },
  "token": "Skill-specific session information"
}

Request parameters

The following table shows the definition of the task-specific input parameter.

Field Description Type Required

input

Input parameters for the task request.

Object

Yes

input.products

List of Amazon products.
Maximum items: 1.

Array of ProductEntity objects

Yes

input.products[].asin

Amazon system identifier for a product.
For details, see ASIN for a product.

String

Yes

input.products[].attribution

Include if your skill is part of the Amazon Associates on Alexa program.

Attribution object

No

Response

The task returns a SessionResumedRequest response that contains the result of the action. To determine if the action succeeded, check the cause.status and task-specific cause.result parameters. The cause.status parameter includes an HTTP status code. For a list of status codes, see Status code attributes in SessionResumedRequest.

Response example

The following example shows an error response.

{
    "type": "SessionResumedRequest",
    "requestId": "Unique id for the request",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "en-US",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "Skill-specific session information to restore the skill session",
        "status": {
            "code": "200",
            "message": "OK"
        },
        "result": {
            "code": "AlexaShopping.RetryLaterError",
            "message": "Encountered an error when trying to process the request, please try again later."
        }
    }
}

Response parameters

The following table shows the definition of the task-specific result parameter. The result parameter is optional. For details about the return values, see Result codes.

Field Description Type Required

code

Identifies the error.

String

Yes

message

Human-readable description of the error.

String

Yes

Result codes

Code Message Description

AlexaShopping.InternalError

We're unable to process your request at this time. Please retry your request. If you encounter this error repeatedly, please reach out to Customer Support.

Internal problem or outage prevented Alexa Shopping from completing your request.

AlexaShopping.InvalidTaskForMarketplace

This operation is not available for this locale.

Requested Alexa Shopping action isn't supported in this locale.

AlexaShopping.ItemNotEligible

The item you specified is not eligible for Alexa Shopping Actions.
Or, the item is not accessible through Alexa Shopping.

Indicates that the item isn't eligible for use with Alexa Shopping.
For example, the item is digital or the item isn't supported for legal reasons.

AlexaShopping.NoOffersFound

We did not find any matches for your request.

Request item wasn't found. For example, the item is out of stock.

AlexaShopping.RetryLaterError

We encountered an error when trying to process the request, please try again later.

Issue occurred while executing the task. For example, the customer has invalid settings or Alexa Shopping had a temporary issue.
The issue is recoverable. Try again later.

Buy products action

Purchase the specified products. Include the request as a directive input from your response handler.

Request

To enable the customer to purchase the product, add a Connections.StartConnection directive to your response.

Request example

{
    "type": "Connections.StartConnection",
    "uri": "connection://AMAZON.BuyShoppingProducts/1",
    "input": {
        "products": [{
            "asin": "ASIN1",
            "attribution": {
                "associateId": "some.associate.id",
                "trackingId": "some.tracking.id"
            }
        }]
    },
    "token": "PurchaseProductToken"
}

Request parameters

The following table shows the definition of the task-specific input parameter.

Field Description Type Required

input

Input parameters for the task request.

Object

Yes

input.products

List of Amazon products.
Maximum items: 1.

Array of ProductEntity objects

Yes

input.products[].asin

Amazon system identifier for a product.
For details, see ASIN for a product.

String

Yes

input.products[].attribution

Include if your skill is part of the Amazon Associates on Alexa program.

Attribution object

No

Response

The task returns a SessionResumedRequest response that contains the result of the action. To determine if the action succeeded, check the cause.status and task-specific cause.result parameters. The cause.status parameter includes an HTTP status code. For a list of status codes, see Status code attributes in SessionResumedRequest.

Response example

The following example shows an error response.

{
    "type": "SessionResumedRequest",
    "requestId": "Unique id for the request",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "en-US",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "Skill-specific session information to restore the skill session",
        "status": {
            "code": "200",
            "message": "OK"
        },
        "result": {
            "code": "AlexaShopping.RetryLaterError",
            "message": "Encountered an error when trying to process the request, please try again later."
        }
    }
}

Response parameters

The following table shows the definition of the task-specific result parameter. The result parameter is optional. For details about the return values, see Result codes.

Field Description Type Required

code

Identifies the error.

String

Yes

message

Human-readable description of the error.

String

Yes

Result codes

Code Message Description

AlexaShopping.InternalError

We're unable to process your request at this time. Please retry your request. If you encounter this error repeatedly, please reach out to Customer Support.

Internal problem or outage prevented Alexa Shopping from completing your request.

AlexaShopping.InvalidTaskForMarketplace

This operation is not available for this locale.

Requested Alexa Shopping action isn't supported in this locale.

AlexaShopping.ItemNotEligible

The item you specified is not eligible for Alexa Shopping Actions.
Or, the item is not accessible through Alexa Shopping.

Indicates that the item isn't eligible for use with Alexa Shopping.
For example, the item is digital or the item isn't supported for legal reasons.

AlexaShopping.NoOffersFound

We did not find any matches for your request.

Request item wasn't found. For example, the item is out of stock.

AlexaShopping.RetryLaterError

We encountered an error when trying to process the request, please try again later.

Issue occurred while executing the task. For example, the customer has invalid settings or Alexa Shopping had a temporary issue.
The issue is recoverable. Try again later.

Recommend products

Recommend products to the customer. Include the request as a directive input from your response handler.

Request

To enable the customer to hear recommendations for specific products, add a Connections.StartConnection directive to your response.

Request example

{
    "type": "Connections.StartConnection",
    "uri": "connection://AMAZON.RecommendShoppingProducts/1",
    "input": {
        "products": [{
                "asin": "ASIN1"
            },
            {
                "asin": "ASIN2",
            },
            {
                "asin": "ASIN3"
            }
        ],
        "attribution": {
            "associateId": "some.associate.id.1",
            "trackingId": "some.tracking.id.1"
        }
    },
    "token": "RecommendProducts",
    "onCompletion": "SEND_ERRORS_ONLY"
}

Request parameters

The following table shows the definition of the task-specific input parameter.

Field Description Type Required

input

Input parameters for the task request.

Object

Yes

input.products

List of Amazon products.
Maximum items: 10.

Array of ProductEntity objects

Yes

input.products[].asin

Amazon system identifier for a product.
For details, see ASIN for a product.

String

Yes

input.attribution

Include if your skill is part of the Amazon Associates on Alexa program. This attribution applies to all products.

Attribution object

No

Response

Alexa sends a response on skill connection failure only. For details, see System.ExceptionEncountered.

Response example

The following example shows an error response.

{
    "type": "System.ExceptionEncountered",
    "requestId": "Unique id for the request",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "en-US",
    "error": {
        "type": "error code",
        "message": "description of the error that occurred"
    },
    "cause": {
        "requestId": "unique identifier for the task that caused the error"
    }
}

Response parameters

There are no task-specific response parameters. Use the cause.requestId to correlate the error with the request.

Object definitions

Attribution object

To earn commission on qualifying purchases, include the Attribution object in your shopping action request. Include this object for live skills that are part of the Amazon Associates on Alexa program only.

The following table shows the definition of the Attribute object.

Field Description Type Required

associateId

Identifies your Associates account.

String

Yes

trackingId

Optional identifier to track this skill.
For more detail about tracking IDs in your Associates account, see Using Tracking IDs.

String

No

ProductEntity object

The ProductEntity object represents a unique product within Amazon. To find the product identifier, locate the Amazon Standard Identification Number (ASIN) on the product detail page on the Amazon retail website. For details, see Product identity.

Field Description Type Required

asin

Amazon system identifier for a product. For details, see ASIN for a product.

String

Yes