API ReferenceSDK & PluginsFAQsContact Us
API Reference

Requests and Responses

Some methods require data for input; others have no output.

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:

NameTypeDescription
RequestIdUUIDA unique identification of this request. Used by Feeds.
RequestActionStringThe name of the method that was called (i.e., the Action parameter of the request).
ResponseTypeStringThe response type contained in the
Body, or empty if none.
TimestampDateTimeTime at which the request was sent, in ISO 8601 format.
BodySubsectionAdditional 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:

NameTypeDescription
RequestActionStringThe method that triggered the error.
ErrorTypeStringThe error's origin (either Sender or Platform)
ErrorCodeIntegerThe internal error code (see Errors).
ErrorMessageStringHuman-readable error message.
ErrorDetailSubsectionThe 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.