Requests and Responses

While most methods are called via GET, some write methods get additional request data sent via POST.

All methods return a response document, which indicates the status of the operation (either
Success or Error) and optionally provides results and/or details related to the specified action.

Additional Request Data via POST

As we have seen, all methods are called via HTTP. Some via GET and some via POST.

All calls always take the Action, Timestamp, UserID, Version and Signature parameters.
Often, additional parameters are added. E.g., GetProducts takes additional parameters, such as a Search parameter.

But sometimes the data that needs to be supplied is more than what can be transported in request parameters. In those cases, additional data is sent to the server using a POST request. The data must be in XML format (even if the Format parameter is set to 'JSON'). All data (including parameter names and values) must be UTF8-encoded (which should be indicated in the XML preamble) and uploaded as MIME type application/x-www-form-urlencoded.

The following might be additional data sent to the ProductUpdate method:

<?xml version="1.0" encoding="UTF-8" ?>
<Request>
  <Product>
    <SellerSku>SKU-AAAA</SellerSku>
    <Price>10.0</Price>
    <SaleStartDate>2015-07-01T11:11:11+0000</SaleStartDate>
    <SaleEndDate>2015-07-01T11:11:11+0000</SaleEndDate>
    <SalePrice>8.0</SalePrice>
  </Product>
  <Product>
    <SellerSku>SKU-BBBB</SellerSku>
    <Price>32.5</Price>
  </Product>
</Request>

📘
GET or POST
Whether to use GET or POST is specific to the Method you are calling and is indicated in this documentation. Even if no additional data needs to be uploaded for a request, you must use POST if that is the specified HTTP verb for the method.

📘
POST request size limitations
According to the SC standard web server setup maximum POST request body size is 128MB.

Non-Data Results

Some methods return long XML documents. E.g., GetProducts will return a very long XML document, listing each product. The syntax of these responses is explained in detail on the reference page for the method.

But a number of methods return no data. In those cases, there is still a response returned. We call this the SuccessResponse. Depending on the Format parameter that was passed in, it can be in JSON or XML (there are tabs below to see either):

<?xml version="1.0" encoding="UTF-8"?>
<SuccessResponse>
  <Head>
    <RequestId>13e55362-3cc4-446b-b3db-c1df0900ae9e</RequestId>
    <RequestAction>PriceFeed</RequestAction>
    <ResponseType></ResponseType>
    <Timestamp>2015-07-01T11:11:11+0000</Timestamp>
  </Head>
  <Body/>
</SuccessResponse>

{
  "SuccessResponse": {
    "Head": {
      "RequestId": "13e55362-3cc4-446b-b3db-c1df0900ae9e",
      "RequestAction": "PriceFeed",
      "ResponseType": "",
      "Timestamp": "2015-07-01T11:11:11+0000"
    },
    "Body": ""
  }
}

The fields in the section are always the same, regardless of whether a method returns data in the Body section or not. The meaning of the data in a SuccessResponse is as follows:

Name	Type	Description
RequestId	UUID	A unique identification of this request. Used by Feeds.
RequestAction	String	The name of the method that was called (i.e., the Action parameter of the request).
ResponseType	String	The response type contained in the Body, or empty if none.
Timestamp	DateTime	Time at which the request was sent, in ISO 8601 format.
Body	Subsection	Additional Data as described by the function's documentation.

Similarly, there is an ErrorResponse. It also has a section, which is often empty, but can be used to provide additional information to the error. Here is an example error message that has a Body:

<?xml version="1.0" encoding="UTF-8"?>
<ErrorResponse>
  <Head>
    <RequestAction>Price</RequestAction>
    <ErrorType>Sender</ErrorType>
    <ErrorCode>1000</ErrorCode>
    <ErrorMessage>Format Error Detected</ErrorMessage>
  </Head>
  <Body>
    <ErrorDetail>
      <Field>StandardPrice</Field>
      <Message>Field must contain a positive number with a dot as decimal
        separator and 2 decimals (e.g. 120.00)
      </Message>
      <Value>10.0x</Value>
      <SellerSku>Example Seller SKU</SellerSku>
    </ErrorDetail>
  </Body>
</ErrorResponse>

Response:
{
  "ErrorResponse": {
    "Head": {
      "RequestAction": "ProductUpdate",
      "ErrorType": "Platform",
      "ErrorCode": "1000",
      "ErrorMessage": "Could not save product: 0, A exact match of the document is being processed"
    },
    "Body": ""
  }
}

Here too, the fields have a fixed meaning across all methods:

Name	Type	Description
RequestAction	String	The method that triggered the error.
ErrorType	String	The error's origin (either Sender or Platform)
ErrorCode	Integer	The internal error code (see Errors).
ErrorMessage	String	Human-readable error message.
ErrorDetail	Subsection	The error response may contain these subsections in its body, one per error. It contains fields specific to the error. At most 50 ErrorDetails are provided.

Requests and Responses

Additional Request Data via POST

📘
GET or POST

📘
POST request size limitations

Non-Data Results

Additional Request Data via POST

📘GET or POST

📘POST request size limitations

Non-Data Results

📘
GET or POST

📘
POST request size limitations