Requests and responses

API calls require data for input and return output as the 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

All API methods are called via HTTP, some via GET and some via POST.

All calls always take the Action, Timestamp, UserID, Version and Signature parameters. Some additional parameters can also be specified. For example, GetProducts takes additional parameters, such as the Search parameter.

However, 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 example shows 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 depends on the method you are calling and is indicated in the Definition section of each API method 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 limitation

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

Non-data results

Some methods return long XML documents. For example, 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.

A number of methods return no data. In those cases, a response will also be returned, which is called Success Response. Depending on the Format parameter that was passed in, it can be in JSON or XML format. See the following examples.

<?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 Success Response is as follows.

NameTypeDescription
RequestIdUUIDThe unique identification of this request.
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 when the request was sent, in ISO 8601 format.
BodysubsectionAdditional data as described by the function documentation.

Similarly, there is an Error Response. It also has a section, which is often empty, but can be used to provide additional information about 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": ""
  }
}

The meaning of the data in an Error Response is as follows.

NameTypeDescription
RequestActionstringThe method that triggered the error.
ErrorTypestringThe origin of the error (either Sender or Platform).
ErrorCodeintegerThe internal error code (see Error messages).
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 can be provided.