Solicitations API v1 Reference
Send non-critical solicitations to buyers.
Overview
With the Solicitations API you can build applications that send non-critical solicitations to buyers. You can get a list of solicitation types that are available for an order that you specify, then call an operation that sends a solicitation to the buyer for that order. Buyers cannot respond to solicitations sent by this API, and these solicitations do not appear in the Messaging section of Seller Central or in the recipient's Message Center. The Solicitations API returns responses that are formed according to the JSON Hypertext Application Language (HAL) standard.
Version information
Version : v1
Contact information
Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html
License information
License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
URI scheme
Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS
Consumes
application/json
Produces
application/hal+json
Operations
getSolicitationActionsForOrder
createProductReviewAndSellerFeedbackSolicitation
Paths
GET /solicitations/v1/orders/{amazonOrderId}
Operation: getSolicitationActionsForOrder
Description
Returns a list of solicitation types that are available for an order that you specify. A solicitation type is represented by an actions object, which contains a path and query parameter(s). You can use the path and parameter(s) to call an operation that sends a solicitation. Currently only the productReviewAndSellerFeedbackSolicitation solicitation type is available.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | amazonOrderId required | An Amazon order identifier. This specifies the order for which you want a list of available solicitation types. | string |
| Query | marketplaceIds required | A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified. Max count : 1 | < string > array |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Returns hypermedia links under the _links.actions key that specify which solicitation actions are allowed for the order. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 404 | The resource specified does not exist. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 413 | The request size exceeded the maximum accepted size. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 415 | The request payload is in an unsupported format. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
| 503 | Temporary overloading or maintenance of the server. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | GetSolicitationActionsForOrderResponse |
POST /solicitations/v1/orders/{amazonOrderId}/solicitations/productReviewAndSellerFeedback
Operation: createProductReviewAndSellerFeedbackSolicitation
Description
Sends a solicitation to a buyer asking for seller feedback and a product review for the specified order. Send only one productReviewAndSellerFeedback or free form proactive message per order.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | amazonOrderId required | An Amazon order identifier. This specifies the order for which a solicitation is sent. | string |
| Query | marketplaceIds required | A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified. Max count : 1 | < string > array |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 201 | The message was created for the order. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 404 | The resource specified does not exist. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 413 | The request size exceeded the maximum accepted size. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 415 | The request payload is in an unsupported format. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
| 503 | Temporary overloading or maintenance of the server. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string) : Unique request reference identifier. | CreateProductReviewAndSellerFeedbackSolicitationResponse |
Definitions
LinkObject
A Link object.
| Name | Description | Schema |
|---|---|---|
| href required | A URI for this object. | string |
| name optional | An identifier for this object. | string |
SolicitationsAction
A simple object containing the name of the template.
| Name | Schema |
|---|---|
| name required | string |
Schema
A JSON schema document describing the expected payload of the action. This object can be validated against http://json-schema.org/draft-04/schema.
Type : object
GetSolicitationActionsForOrderResponse
The response schema for the getSolicitationActionsForOrder operation.
| Name | Description | Schema |
|---|---|---|
| self required | - | LinkObject |
| actions required | Eligible actions for the specified amazonOrderId. | < LinkObject > array |
| Name | Schema |
|---|---|
| actions required | < GetSolicitationActionResponse > array |
GetSolicitationActionResponse
Describes a solicitation action that can be taken for an order. Provides a JSON Hypertext Application Language (HAL) link to the JSON schema document that describes the expected input.
| Name | Description | Schema |
|---|---|---|
| _links optional | - | _links |
| _embedded optional | - | _embedded |
| payload optional | A simple object containing the name of the template. | SolicitationsAction |
| errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
| Name | Schema |
|---|---|
| self required | LinkObject |
| schema required | LinkObject |
| Name | Schema |
|---|---|
| schema optional | GetSchemaResponse |
GetSchemaResponse
| Name | Description | Schema |
|---|---|---|
| _links optional | - | _links |
| payload optional | A JSON schema document describing the expected payload of the action. This object can be validated against http://json-schema.org/draft-04/schema. | Schema |
| errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
| Name | Schema |
|---|---|
| self required | LinkObject |
CreateProductReviewAndSellerFeedbackSolicitationResponse
The response schema for the createProductReviewAndSellerFeedbackSolicitation operation.
| Name | Description | Schema |
|---|---|---|
| errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
ErrorList
A list of error responses returned when a request is unsuccessful.
Type : < Error > array
Error
Error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition in a human-readable form. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
Updated 4 months ago