Solicitations API v1 Use Case Guide
Send consistent, high-quality solicitations to buyers.
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
ORDER_CHANGE
notificationFor more information, refer to Tutorial: Subscribe to the ORDER_CHANGE Notification.
Step 2. Validate the OrderStatus
parameter
OrderStatus
parameterThe 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
EarliestDeliveryDate
and LatestDeliveryDate
parametersYou 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
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": ""
}
]
}
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.
Updated 29 days ago