Developer HubAPI StatusSupport

Solicitations API v1 Use Case Guide

Send consistent, high-quality solicitations to buyers.

API Version: v1

What is the Solicitations API?

The Selling Partner API for Solicitations (Solicitations API) helps you build applications that let sellers send consistent, high-quality solicitations to buyers. Sellers can request both a product review and seller feedback by sending a single template-based email.

Tutorial: Solicit feedback for an order

This tutorial shows you how to solicit a product review and seller feedback for an order. You first verify that an order is available for solicitation, then create the solicitation request.

Prerequisites

To complete this tutorial you will need:

Step 1. Verify that an order is available for solicitation

Call the getSolicitationActionsForOrder operation, passing the following parameters:

Path parameter

Parameter Description Required
amazonOrderId

An Amazon order identifier. This specifies the order for which you want a list of available solicitation types.

Type: string

 Yes

Query parameter

Parameter Description Required
marketplaceIds

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Type: array[String]

 Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/solicitations/v1/orders/333-7777777-7777777
  ?marketplaceIds=ATVPDKIKX0DER

Response examples

Response example when no solicitation actions are available:

{
  "_links": {
    "actions": [],
    "self": {
      "href": "/solicitations/v1/orders/111-1111111-1111111?marketplaceIds=ATVPDKIKX0DER"
    }
  },
  "_embedded": {
    "actions": []
  }
}

Response example when solicitation actions are available:

{
  "_links": {
    "actions": [
      {
        "href": "/solicitations/v1/orders/111-1111111-1111111/solicitations/productReviewAndSellerFeedback?marketplaceIds=ATVPDKIKX0DER",
        "name": "productReviewAndSellerFeedback"
      }
    ],
    "self": {
      "href": "/solicitations/v1/orders/111-1111111-1111111?marketplaceIds=ATVPDKIKX0DER"
    }
  },
  "_embedded": {
    "actions": [
      {
        "_links": {
          "schema": {
            "href": "/solicitations/v1/orders/111-1111111-1111111/solicitations/productReviewAndSellerFeedback/schema",
            "name": "productReviewAndSellerFeedback"
          },
          "self": {
            "href": "/solicitations/v1/orders/111-1111111-1111111/solicitations/productReviewAndSellerFeedback?marketplaceIds=ATVPDKIKX0DER",
            "name": "productReviewAndSellerFeedback"
          }
        },
        "_embedded": {
          "schema": {
            "_links": {
              "self": {
                "href": "/solicitations/v1/orders/111-1111111-1111111/solicitations/productReviewAndSellerFeedback/schema",
                "name": "productReviewAndSellerFeedback"
              }
            },
            "type": "object",
            "name": "productReviewAndSellerFeedback",
            "title": "Request seller feedback and product review",
            "description": "Request seller feedback and product review",
            "properties": {},
            "required": [],
            "$schema": "http://json-schema.org/draft-04/schema#",
            "x-ui-hidden": true
          }
        },
        "name": "productReviewAndSellerFeedback",
        "title": "Request seller feedback and product review"
      }
    ]
  }
}

Step 2. Create a product review solicitation

If the productReviewAndSellerFeedback action is listed in the response, call the createProductReviewAndSellerFeedbackSolicitation operation, passing the following parameters:

Path parameter

Parameter Description Required
amazonOrderId

An Amazon order identifier. This specifies the order for which a solicitation is sent.

Type: string

 Yes

Query parameter

Parameter Description Required
marketplaceIds

A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.

Type: array[String]

 Yes

Request example

POST https://sellingpartnerapi-na.amazon.com/solicitations/v1/orders/333-7777777-7777777/solicitations/productReviewAndSellerFeedback
  ?marketplaceIds=ATVPDKIKX0DER

Response examples

Response example for an eligible order:

{}

Response example for an ineligible order:

{
  "errors": [
    {
      "code": "Unauthorized",
      "message": "The requested solicitation is not available for this amazonOrderId.",
      "details": ""
    }
  ]
}

Updated about 1 month ago