Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation

Deprecation Notice:

Amazon Marketplace Web Service (MWS) will no longer be available after March 31, 2024. All MWS developers must migrate to Selling Partner API (SP-API) to avoid service disruptions. Refer to the Migration Hub for more information.

Amazon MWS Documentation

Using the Amazon MWS client libraries

Each Amazon MWS API section has its own client library that contains code for doing many common tasks when working with Amazon MWS. By using an Amazon MWS client library, you save time and you know the request you send is correctly formatted. For example, the Amazon MWS client libraries perform the following tasks for you:

  • Request Signature - creates a valid request HMAC-SHA signature. Each request must have a valid signature or the request is rejected. A request signature is calculated using your Secret Access Key, which is a shared secret, given to you when you registered, and known only to you and Amazon MWS.
  • Timestamp - adds a timestamp on each request you submit. Each request must contain the timestamp of the request.
  • Requests - builds a valid request for you based on the operation you select and the parameters you enter.
  • User-Agent header - creates the User-Agent header.
  • Stream - creates a stream you use to receive downloaded reports when using the GetReport operation.

If you create your own client library

You can create your own client library for use with Amazon MWS. Your code should construct and sign a request in the format expected by Amazon MWS, and then you parse the resulting XML response.

You access Amazon MWS by following these steps:

  1. Determine the correct Amazon MWS endpoint to use.

    Amazon MWS endpoints vary by region for the marketplace you are trying to access. Consult Amazon MWS endpoints and MarketplaceId values for the correct endpoint to use for your intended marketplace.

  2. Determine the throttling limits for the operation you want to submit.

    Every Amazon MWS API has limits to how often it can be invoked over certain time periods. If you exceed these limits, your call will fail and you will have to wait for your next call. This waiting period will be based on the refresh rate for the API. For more information, see Throttling: Limits to how often you can submit requests.

    For each individual API, see the Throttling section on the API reference page for specific throttling limits.

  3. Familiarize yourself with the MWS request format.

    Amazon MWS supports query requests for calling web service actions. Query requests are simple HTTP requests, using the GET or POST method in the HTTP request-line. The HTTP request-line consists of the HTTP method, the URL, and the protocol version. The URL contains the path and query parameters. The HTTP Body contains the HTTP body request parameters. Amazon MWS requires the use of HTTPS in order to prevent third-party eavesdropping on your communication with Amazon.

    Each of the HTTP header lines must be terminated with a carriage return and a line feed. Query requests must contain an Action parameter to indicate the action to be performed. The response is an XML document.

  4. Set the timestamp for your request.

    See Working with Timestamps.

  5. Construct a query string for the request.

    See Creating a Canonicalized Query String.

  6. Sign the query string and create the request.

    See Signing a Query Request.

  7. Set the User-Agent Header for your application.

    See Creating your User-Agent Header.

  8. Send the correctly formatted HTTP request-line and the HTTP header parameters containing the User-Agent header to the endpoint for your Amazon marketplace.

    Amazon MWS requires that the size of the HTTP request-line must be less than 8190 bytes and the size of the HTTP request body be less than 2048 MB.

    If you are sending an HTTP request-line that exceeds the limit, then you must reduce your HTTP query parameters and use the HTTP request body parameters.
    Note: The request-line limit doesn't matter if you are using the Amazon MWS client libraries.
    The URL contains the following parts:

    The following is an example of a complete request URL that you could submit. The actual request should not contain white space or line breaks.
  9. Parse the response.