solicitations.json

{
  "swagger": "2.0",
  "info": {
    "description": "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 <a href=https://tools.ietf.org/html/draft-kelly-json-hal-08>JSON Hypertext Application Language</a> (HAL) standard.",
    "version": "v1",
    "title": "Selling Partner API for Solicitations",
    "contact": {
      "name": "Selling Partner API Developer Support",
      "url": "https://sellercentral.amazon.com/gp/mws/contactus.html"
    },
    "license": {
      "name": "Apache License 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0"
    }
  },
  "host": "sellingpartnerapi-na.amazon.com",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/hal+json"
  ],
  "paths": {
    "/solicitations/v1/orders/{amazonOrderId}": {
      "get": {
        "tags": [
          "solicitations"
        ],
        "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.\n\n**Usage Plan:**\n\n| Rate (requests per second) | Burst |\n| ---- | ---- |\n| 1 | 5 |\n\nThe `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](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits-in-the-sp-api).",
        "operationId": "getSolicitationActionsForOrder",
        "parameters": [
          {
            "name": "amazonOrderId",
            "in": "path",
            "description": "An Amazon order identifier. This specifies the order for which you want a list of available solicitation types.",
            "required": true,
            "type": "string"
          },
          {
            "name": "marketplaceIds",
            "in": "query",
            "description": "A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.",
            "required": true,
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Returns hypermedia links under the _links.actions key that specify which solicitation actions are allowed for the order.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "examples": {
              "application/hal+json": {
                "_links": {
                  "actions": [
                    {
                      "href": "/solicitations/v1/orders/903-1671087-0812628/solicitations/productReviewAndSellerFeedback?marketplaceIds=ATVPDKIKX0DER",
                      "name": "productReviewAndSellerFeedback"
                    }
                  ],
                  "self": {
                    "href": "/solicitations/v1/orders/903-1671087-0812628?marketplaceIds=ATVPDKIKX0DER"
                  }
                },
                "_embedded": {
                  "actions": [
                    {
                      "_links": {
                        "schema": {
                          "href": "/solicitations/v1/orders/903-1671087-0812628/solicitations/productReviewAndSellerFeedback/schema",
                          "name": "productReviewAndSellerFeedback"
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            },
            "x-amzn-api-sandbox": {
              "static": [
                {
                  "request": {
                    "parameters": {
                      "amazonOrderId": {
                        "value": "123-1234567-1234567"
                      },
                      "marketplaceIds": {
                        "value": [
                          "ATVPDKIKX0DER"
                        ]
                      }
                    }
                  },
                  "response": {
                    "_links": {
                      "actions": [
                        {
                          "href": "/solicitations/v1/orders/123-1234567-1234567/solicitations/productReviewAndSellerFeedback?marketplaceIds=ATVPDKIKX0DER",
                          "name": "productReviewAndSellerFeedback"
                        }
                      ],
                      "self": {
                        "href": "/solicitations/v1/orders/123-1234567-1234567?marketplaceIds=ATVPDKIKX0DER"
                      }
                    }
                  }
                }
              ]
            }
          },
          "400": {
            "description": "Request has missing or invalid parameters and cannot be parsed.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "403": {
            "description": "Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "404": {
            "description": "The resource specified does not exist.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "413": {
            "description": "The request size exceeded the maximum accepted size.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "415": {
            "description": "The request payload is in an unsupported format.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "429": {
            "description": "The frequency of requests was greater than allowed.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "500": {
            "description": "An unexpected condition occurred that prevented the server from fulfilling the request.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "503": {
            "description": "Temporary overloading or maintenance of the server.",
            "schema": {
              "$ref": "#/definitions/GetSolicitationActionsForOrderResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          }
        }
      }
    },
    "/solicitations/v1/orders/{amazonOrderId}/solicitations/productReviewAndSellerFeedback": {
      "post": {
        "tags": [
          "solicitations"
        ],
        "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.\n\n**Usage Plan:**\n\n| Rate (requests per second) | Burst |\n| ---- | ---- |\n| 1 | 5 |\n\nThe `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](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits-in-the-sp-api).",
        "operationId": "createProductReviewAndSellerFeedbackSolicitation",
        "parameters": [
          {
            "name": "amazonOrderId",
            "in": "path",
            "description": "An Amazon order identifier. This specifies the order for which a solicitation is sent.",
            "required": true,
            "type": "string"
          },
          {
            "name": "marketplaceIds",
            "in": "query",
            "description": "A marketplace identifier. This specifies the marketplace in which the order was placed. Only one marketplace can be specified.",
            "required": true,
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 1
          }
        ],
        "responses": {
          "201": {
            "description": "The message was created for the order.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            },
            "x-amzn-api-sandbox": {
              "static": [
                {
                  "request": {
                    "parameters": {
                      "amazonOrderId": {
                        "value": "123-1234567-1234567"
                      }
                    }
                  },
                  "response": {}
                }
              ]
            }
          },
          "400": {
            "description": "Request has missing or invalid parameters and cannot be parsed.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "403": {
            "description": "Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "404": {
            "description": "The resource specified does not exist.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "413": {
            "description": "The request size exceeded the maximum accepted size.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "415": {
            "description": "The request payload is in an unsupported format.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "429": {
            "description": "The frequency of requests was greater than allowed.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "500": {
            "description": "An unexpected condition occurred that prevented the server from fulfilling the request.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          },
          "503": {
            "description": "Temporary overloading or maintenance of the server.",
            "schema": {
              "$ref": "#/definitions/CreateProductReviewAndSellerFeedbackSolicitationResponse"
            },
            "headers": {
              "x-amzn-RateLimit-Limit": {
                "type": "string",
                "description": "Your rate limit (requests per second) for this operation.\n_Note:_ For this status code, the rate limit header is deprecated and no longer returned."
              },
              "x-amzn-RequestId": {
                "type": "string",
                "description": "Unique request reference identifier."
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "LinkObject": {
      "type": "object",
      "required": [
        "href"
      ],
      "properties": {
        "href": {
          "type": "string",
          "description": "A URI for this object."
        },
        "name": {
          "type": "string",
          "description": "An identifier for this object."
        }
      },
      "description": "A Link object."
    },
    "SolicitationsAction": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "description": "A simple object containing the name of the template."
    },
    "Schema": {
      "type": "object",
      "description": "A JSON schema document describing the expected payload of the action. This object can be validated against <a href=http://json-schema.org/draft-04/schema>http://json-schema.org/draft-04/schema</a>.",
      "additionalProperties": {}
    },
    "GetSolicitationActionsForOrderResponse": {
      "type": "object",
      "properties": {
        "_links": {
          "type": "object",
          "properties": {
            "self": {
              "$ref": "#/definitions/LinkObject"
            },
            "actions": {
              "type": "array",
              "description": "Eligible actions for the specified amazonOrderId.",
              "items": {
                "$ref": "#/definitions/LinkObject"
              }
            }
          },
          "required": [
            "actions",
            "self"
          ]
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "actions": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/GetSolicitationActionResponse"
              }
            }
          },
          "required": [
            "actions"
          ]
        },
        "errors": {
          "$ref": "#/definitions/ErrorList"
        }
      },
      "description": "The response schema for the getSolicitationActionsForOrder operation."
    },
    "GetSolicitationActionResponse": {
      "type": "object",
      "properties": {
        "_links": {
          "type": "object",
          "properties": {
            "self": {
              "$ref": "#/definitions/LinkObject"
            },
            "schema": {
              "$ref": "#/definitions/LinkObject"
            }
          },
          "required": [
            "schema",
            "self"
          ]
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "schema": {
              "$ref": "#/definitions/GetSchemaResponse"
            }
          }
        },
        "payload": {
          "$ref": "#/definitions/SolicitationsAction"
        },
        "errors": {
          "$ref": "#/definitions/ErrorList"
        }
      },
      "description": "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."
    },
    "GetSchemaResponse": {
      "type": "object",
      "properties": {
        "_links": {
          "type": "object",
          "properties": {
            "self": {
              "$ref": "#/definitions/LinkObject"
            }
          },
          "required": [
            "self"
          ]
        },
        "payload": {
          "$ref": "#/definitions/Schema"
        },
        "errors": {
          "$ref": "#/definitions/ErrorList"
        }
      }
    },
    "CreateProductReviewAndSellerFeedbackSolicitationResponse": {
      "type": "object",
      "properties": {
        "errors": {
          "$ref": "#/definitions/ErrorList"
        }
      },
      "description": "The response schema for the createProductReviewAndSellerFeedbackSolicitation operation."
    },
    "ErrorList": {
      "type": "array",
      "description": "A list of error responses returned when a request is unsuccessful.",
      "items": {
        "$ref": "#/definitions/Error"
      }
    },
    "Error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "An error code that identifies the type of error that occurred."
        },
        "message": {
          "type": "string",
          "description": "A message that describes the error condition."
        },
        "details": {
          "type": "string",
          "description": "Additional details that can help the caller understand or fix the issue."
        }
      },
      "description": "Error response returned when the request is unsuccessful."
    }
  }
}