Solicitations API v1 Use Case Guide

API Version: v1

What is the Solicitations API?

You can use the Selling Partner API for Solicitations (Solicitations API) to 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 1: Set up the Solicitations API

This guide demonstrates how to set up the Solicitations API before soliciting feedback.

Prerequisites

To complete this tutorial, you need:

• An order available for solicitation.
• The Buyer Solicitation role or the Product Listing role.

Step 1. Subscribe to the ORDER_CHANGE notification

For more information, refer to Tutorial: Subscribe to the ORDER_CHANGE Notification.

Step 2. Validate the OrderStatus parameter

The Amazon Simple Queue Service (SQS) workflows receives the payload of the ORDER_CHANGE notification. You can use Amazon SQS to validate the OrderStatus parameter. Check that the OrderStatus value has changed to Shipped. Eliminate redundancies to make sure whether a solicitation has already been dispatched for a specific order. For more information on how to poll the SQS queue, refer to Tutorial: Set up notifications (Amazon Simple Queue Service workflow).

Step 3. Check the EarliestDeliveryDate and LatestDeliveryDate parameters

You can request solicitation within a time frame of five days after the EarliestDeliveryDate to 30 days after the LatestDeliveryDate. Calling the Solicitations API outside this time frame will lead to unexpected API errors.

Step 4. Store key identifiers

Archive or cache the amazonOrderId and MarketplaceId parameters. These identifiers are required to solicit reviews in the future.

Now you are ready to solicit feedback.

Tutorial 2: 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 need:

• An order available for solicitation.
• The Buyer Solicitation role or the Product Listing role.

Step 1. Verify that an order is available for solicitation

Call the getSolicitationActionsForOrder operation, passing the following parameters:

Path parameter

Query parameter

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

Query parameter

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": ""
    }
  ]
}

Best practices

When you solicit reviews, ensure that you:

• Seek reviews for orders that have been delivered.
• Prompt for feedback within the allowed time frame.

Note that you cannot:

• Selectively seek positive reviews.
• Request alterations to existing reviews.
• Offer rewards or incentives for reviews.

For more information on how to ethically navigate solicitations, review the Anti-Manipulation Policy for Customer Reviews.

Turn negative feedback into opportunities

When you receive negative reviews, your effort to resolve the buyer's issue can change the narrative. Once you have resolved the buyer's problem, call the createNegativeFeedbackRemoval operation from the Messaging API. Sellers can use this operation to ask the buyer to remove the unfavorable feedback. This offers sellers a second chance and underscores their commitment to customer satisfaction.