Connecting to the Amazon API (MWS)

In this article, we propose to consider the peculiarities of connecting to the Amazon Marketplace Web Service (MWS). Let's explore the process of obtaining a list of orders for reference.

Getting started with MWS

The data format received in MWS differs from JSON and XML and represents a unique format where nesting is done using the separator ".". For example, in JSON, if you need to pass the key "b" with the value "c", nested under the key "a" - {"a": { "b": "c"}}, in MWS, it will look like "a.b" with the value "c". The format of the data received in MWS is XML.

The request signature is formed using several parameters:

• "AWSAccessKeyId" - provided by Amazon;
• "SellerId" - a 14-character unique identifier of the Amazon seller, consisting of letters and digits;
• "MWSAuthToken" - a token for trusted developers, which will be described further;
• "SignatureVersion" - the version of the signature method, for example, "2";
• "Timestamp" - the date and time of the request in "ISO 8601" format;
• "Version" - the version of the specific API branch in "YYYY-MM-DD" format;
• "SignatureMethod" - the signature method, for example, "HmacSHA256".

Regarding "SellerId" and "MWSAuthToken," it is necessary to consider Amazon's specific approach to granting developers access to seller accounts. Firstly, the account needs to be switched to developer mode. After that, other sellers can give the new developer access to manage their data through the API. In the seller's account, there is a list of trusted developers, and each of them is assigned a special "MWSAuthToken" key. This key must be provided to the developer to use in the signature of API requests along with the "SellerId." Since a seller who becomes a developer doesn't need to grant access to themselves, when making requests on their behalf, they should indicate the "MWSAuthToken" key with the value "".

Amazon does not provide a sandbox mode, so all the work connecting to the API will be performed with real data. Fine-tuning the signature of requests can be done for GET requests, but there is a risk of breaking something when attempting something more complex. To send requests, you need to use the URL https://mws.amazonaws.com/ .

Fetching orders from Amazon using the API

After successfully configuring the request signature, the API allows retrieving certain data from the personal account, such as the list of orders. The API's functionality is divided into branches based on the objects being worked with: Orders, Products, Fulfillment Inbound Shipments, Fulfillment Outbound Shipments, Feeds, etc. In this case, we will be using the OrdersAPI, which is available at the link http://docs.developer.amazonservices.com/en_US/orders-2013-09-01/Orders_Overview.html .

To retrieve the list of orders, a GET request needs to be made to the address https://mws.amazonaws.com/Orders/2013-09-01 with the parameter "Action" and the value "ListOrders". The "Action" parameter is used for both GET and POST requests and clearly defines the API's functionality. In addition to "ListOrders," filters can be specified to refine the results, but the basic request can be made without them. With the successful configuration of the request signature, the specified URL will return XML with the following structure: ListOrdersResponse (root element), ListOrdersResult (first-level element), and Orders (second-level element), which contains a list of Order elements. Each Order element represents an XML representation of an order on Amazon (fig. 1). Pagination is implemented using the value of the "Action" parameter - "ListOrdersByNextToken". Therefore, if the "ListOrders" request returns the second-level element "NextToken," it means that the seller has more than 100 orders, and at least one more request needs to be made with the parameters "Action" - "ListOrdersByNextToken" and "NextToken" with the value obtained from the previous request. Further pagination pages can be obtained using "ListOrdersByNextToken".

Picture 1

Each order has a set of string properties, such as AmazonOrderId, PurchaseDate, OrderStatus, as well as nested objects like ShippingAddress, OrderTotal, and others. The order information is not entirely suitable for direct use on the website, so to obtain complete information, it is necessary to also retrieve associated products. To retrieve data about the products, you need to make a request with the "Action" parameter set to "GetOrder," also passing the "AmazonOrderId" parameter with the value obtained from the response of the "ListOrders" or "ListOrdersByNextToken" request. The response to this request will contain a list of products identified by the ASIN (pic. 2).

Picture 2

The request to this branch includes the following parameters: "Action" - "GetMatchingProduct" and "ASINList.ASIN.1" - where you pass the ASIN of the desired product. The request can contain up to 10 ASINs by providing their values as parameters "ASINList.ASIN.2," "ASINList.ASIN.3," ..., "ASINList.ASIN.10." For this branch, the request signature will use the value "2011-10-01" for the "Version" parameter. The structure of the response can be found in picture 3.

Picture 3

In all other aspects, error handling and integration with business logic need to be implemented. Additionally, Amazon sets specific limits for the quantity and frequency of requests for each "Action," which must be taken into account separately as needed. Furthermore, in some requests, you can include the "MarketplaceId" parameter, which determines the region. For the USA and Brazil, the domain used is https://mws.amazonservices.com . The value of the parameter "MarketplaceId" for the USA is "ATVPDKIKX0DER", and for Brazil - "A2Q3Y263D00KWC". The value of the "MarketplaceId" parameter for the USA is "ATVPDKIKX0DER," and for Brazil, it is "A2Q3Y263D00KWC."

For a comprehensive list, please refer to http://docs.developer.amazonservices.com/en_US/dev_guide/DG_Endpoints.html .

Illustrating data transmission with an example: assigning a tracking number to an order

Data transmission using the example of assigning a tracking number to an order is performed through the Feeds API. All requests in this category require an additional signature. This signature is based on the content of the feed file, which needs to be transmitted in the body of the POST request. Let's assume that Amazon has an order with the identifier "A," and it is associated with a product with the linkage identifier "B" in a quantity of one unit. We want to specify the tracking number "C" for delivery service "D" using method "E" for this order.

In this case, the file we send will have the following format:

<?xml version="1.0" encoding="iso-8859-1"?> <AmazonEnvelope xsi:noNamespaceSchemaLocation="amzn-envelope.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instancet\"> <Header> <DocumentVersion>1.01</DocumentVersion> <MerchantIdentifier>{{ SellerId }}</MerchantIdentifier> </Header> <MessageType>OrderFulfillment</MessageType> <Message> <MessageID>1</MessageID> <OrderFulfillment> <AmazonOrderID>{{ A }}</AmazonOrderID> <FulfillmentDate>{{ FulfillmentDate }}</FulfillmentDate> <FulfillmentData> <CarrierName>{{ D }}</CarrierName> <ShippingMethod>{{ E }}</ShippingMethod> <ShipperTrackingNumber>{{ C }}</ShipperTrackingNumber> </FulfillmentData> <Item> <AmazonOrderItemCode>{{ B }}</AmazonOrderItemCode> <Quantity>1</Quantity> </Item> </OrderFulfillment> </Message> </AmazonEnvelope>

In addition to the above parameters, we can see SellerId and FulfillmentDate. SellerId is Amazon's unique identifier, discussed earlier, and FulfillmentDate is the shipment date in ISO 8601 format. To sign the feed file, we will use the value of the Content-MD5 header, which is a base64-encoded string resulting from MD5 encoding the file's content. The parameters D and E could, for example, be USPS and USPS First Class, respectively.

The request body is already occupied by a file, so although the request is sent using the POST method, the Action parameters with the value of SubmitFeed and the FeedType with the value of POST_ORDER_FULFILLMENT_DATA must be passed as query string parameters. To transfer the file correctly, use the Content-Type header with the value text/xml.

Due to the potential file size, which can be as large as 2 GB, Amazon does not provide the processing result of the file in the response. Instead, the response will include the ID of the registered feed.

The response will be in the following format:

<?xml version="1.0"?> <SubmitFeedResponse xmlns="http://mws.amazonaws.com/doc/2009-01-01/"> <SubmitFeedResult> <FeedSubmissionInfo> <FeedSubmissionId>{{ FeedSubmissionId }}</FeedSubmissionId> <FeedType>_POST_ORDER_FULFILLMENT_DATA_</FeedType> <SubmittedDate>{{ SubmittedDate }}</SubmittedDate> <FeedProcessingStatus>_SUBMITTED_</FeedProcessingStatus> </FeedSubmissionInfo> </SubmitFeedResult> <ResponseMetadata> <RequestId>{{ RequestId }}</RequestId> </ResponseMetadata> </SubmitFeedResponse>

FeedSubmissionId is the ID of the feed, with which we can later check the result of processing the file. SubmittedDate - feed registration time. RequestId is a request identifier specific to each response from Amazon. Now, over time, and if the file is small, we can make a GET request with the Action parameters GetFeedSubmissionResult and FeedSubmissionId with the previously saved FeedSubmissionId to check the status of the feed.

Other feed downloads work similarly and require knowing the IDs of various entities in Amazon's database, such as A and B, which you can retrieve from your personal account or via the API.