Going global with amazon MWS-API

Going global with amazon MWS-API


Amazon  MWS provides a complete (well, almost complete!) web-based solution for retailers and makes it very easy to handle operations. However, a significant number of challenges emerge as one starts selling on multiple marketplaces. It is not just about localization and formats, there are a lot more differences in the way different marketplaces provide information. Getting a global view of business is really difficult.

My Story

When I was assigned to figure out a nice solution to get an integrated view of data from multiple MWS marketplaces, I was all excited. It was completely a new thing for me. New problems, New technology, Newer challenges. I knew that MWS-API would help. Amazon MWS is a web service API that is used by Amazon sellers and developers to programmatically access data on orders, reports, payments, and more. Amazon Seller Central is a web-based interface provided to a seller to manage the business. MWS APIs are provided by Amazon to perform the same operations programmatically so that sellers can extend, augment, and automate some operations & workflows as required.

However, I totally underestimated the challenges that would show up. I did start by reading and understanding Amazon MWS API docs, but what finally helped most was rolling up the sleeves and jumping into the world of Amazon MWS. In this blog, I have penned the challenges I faced, possible solutions to challenges, pitfalls, and the potential that I see as to how Amazon MWS API can help transform an e-commerce business into a truly global one.


IMO, Amazon’s e-Commerce Platform itself provides enough framework and infrastructure, to ensure the smooth running and growth of your e-commerce business; but Amazon MWS opens a world of opportunities for extending your e-commerce business globally and in ways that you could possibly not imagine. MWS API provides enough actionable information and actions which can help you automate and integrate various customized workflows around customer feedback, inventory management, order tracking, order replacements, operational reporting, financial reporting, and important event notifications. These customized integrations can span multiple geographical marketplaces, sales channels, and public-private cloud instances. In other words, Amazon MWS API is a Swiss-army knife that can help realize an online seller’s vision to differentiate and leapfrog over the competition (other online sellers on Amazon).


I used the Amazon MSW API library for Java & came across a few vexing challenges during the development. One was handling variations in report formats. Following are some of the instances:

The Settlement (Payments) report contains some transactions that are associated with the product whereas some are not. Those which are not associated with the product do not contain SKU (Product identifier). Such transactions are typically shown as empty cells in the SKU column. But, the system may show ‘No SKU Available’ instead of an empty cell, and that could lead to system failure.

We should try to account for such transient behaviors in the system. Hard-coding a specific phrase is not a good idea, because Amazon may introduce a verbiage change that would create another failure. Also, a small change in the code can introduce regressions, hence such code injections should be avoided.

An effective solution to work through such issues is to maintain configuration/property files (also called “Externalization”) which contain configuration data that has the potential to change in the future. So in the above example, one can store all such aliases of “emptiness“ in the Property file as follows:

Property file contents:

EMPTY_SKU_ALIASES = { “ “, “No SKU Available”, “No SKU Present” }

In code,

IF(SKU From Report Matches the value in EMPTY_SKU_ALIASES property)


//SKU is empty. Perform processing according to business logic.


In a case where Amazon introduces new alias for empty cells (e.g. “SKU Not Available”), the property file can be easily modified and that’s it!


Property file modified contents:

EMPTY_SKU_ALIASES = { “ “, “No SKU Available”, “No SKU Present”, “SKU Not Available” }

One more challenging task might be to handle report variations across marketplaces. In some types of reports, the date formats, and number formats vary according to country/marketplace-specific locales. For example, Amazon US reports follow ‘yyyy-mm-dd’ whereas Amazon UK follows ‘dd-mm-yyyy’

To deal with such situations, again the ‘externalization’ technique works very well. A separate property file for each marketplace can be created and all such formats can be stored in that file. Load the property file in code during the initialization of your system and then you are good to handle any of the marketplace-specific format variations!

Externalization also helps to deal with glitches in report formats. If a glitch occurs at Amazon’s end (which changes the report format temporarily), a property file for the affected marketplace can be modified temporarily and once the glitch disappears, revert back to its original version.

For instance, if due to a glitch, the date format in the US report changes to ‘dd-mm-yyyy’ instead of the US locale standard of ‘yyyy-mm-dd’, modifying the date format in the US property file to ‘dd-mm-yyyy’ will fix the issue without touching the codebase.

Amazon documentation is light on variations and discrepancies in report formats and the trick to identifying such variations and glitches is to surround your code with Exception handling. Various types of exceptions can be caught in the code – parsing exceptions, number format exceptions, etc. and email notifications can be sent out to configured email addresses to report the findings. Notification emails can also contain event logs for further investigation.

Exceptions can cause perfectly running stores to stop working, and adding exception handling and externalization to your software system makes it future-proof.


Amazon has provided a web application called ‘Scratchpad that gives the ability to perform API operations “without writing code” and allows developers to explore the API and its nuances. ‘Scratchpad’ displays responses of requests in XML or other formats. Always trying out APIs through code is cumbersome and time-consuming during development so scratchpad presents a very easy option for API exploration.

For other marketplaces visit MWS documentation.


While using MWS, another important concept that you need to be aware of is Throttling – Amazon has introduced throttling to manage its request traffic efficiently. If you fire too many API requests at a time or if you fire them at too high an average rate, the system throttles your requests. 

Throttling can be handled in the code as follows.

1. Try to make a request to Amazon API

while(true) {

try {

GetReportResponse response = _mwsservice.getReport(request); } 



2. If an exception occurs and it is identified as throttling, slow down your request.

For that, calculate (predict) wait time (restoreRate),

catch(MarketplaceWebServiceException e) {

/* To avoid case of infinite throttling (And eventually limit the maximum time to run the system), 
decide your maximum retry count and put a check against it */

If (currentRetryCount > maxRetryCount) {

//Back off

Throw new Exception(“Maximum attempts to throttling exhausted. Please try to run the system after some time”);


If (e.getErrorCode().contains(“Throttled”)) {

//Predict wait time/restoreRate by devising your own formula

restoreRate = (int) ((2 + Math.pow(2, currentRetryCount)) * 60000);


currentRetryCount ++;





3. If (currentRetryCount > maxRetryCount):

This if block is added to handle the case of continuous long-time throttling. We have to put a time limit on the throttling processing part so that the system doesn’t freeze for a long time while being throttled.

4. If (e.getErrorCode().contains(“Throttled”) ):

When the system receives a throttling exception from Amazon, calculate the restore rate. The formula for restore rate is arbitrary. It’s better to devise it keeping in mind that the restore rate increases exponentially for every consecutive throttling


The sky’s the limit as to what level of automation, and extensions can be added to your e-commerce operations using MWS. MWS is a very effective set of APIs, although sometimes a bit variable; the trick to get around the limitations when developing a solid MWS application is to use defensive techniques programming. I have seen it being put to amazing use for automating operations and workflows that resulted in increased selling efficiency, reduced labor requirements, improved response time for customers & increased customer satisfaction.

Share this post