Amazon Marketplace Web Service (MWS)

The second Amazon API I discovered is the Amazon Marketplace Web Service. The previous post covered the Amazon Product Advertising API which was all about helping Amazon to sell products already listed on Amazon. It is intended for Affiliates, not Vendors.

So what is the Amazon Marketplace Web Service? According to Amazon:

Amazon Marketplace Web Service (Amazon MWS) is an integrated web service API that helps Amazon sellers to programmatically exchange data on listings, orders, payments, reports and more.

Good news: The Amazon Marketplace Web Service IS the API for vendors. Bad news: It is large, complex and not that easy to use.

A quick peak at the technical documentation reveals that the Marketplace Web Service contains 13 sets of API calls. Not 13 calls, but 13 sets of calls. Each of these API sets is standalone and distinct. With a different version number. Some as old as 2009, some as recent as 2015. As these different APIs evolve over time you will need to ensure that your code keeps up. The good news is that many of these API sets only have a handful of calls.

The following sets of API's are provided:

  1. Feeds
  2. Reports
  3. Finances
  4. Fulfillment Inbound Shipment
  5. Fulfillment Inventory
  6. Fulfillment Outbound Shipment
  7. Merchant Fulfillment
  8. Off Amazon Payments
  9. Orders
  10. Products
  11. Recommendations
  12. Sellers
  13. Subscriptions

As a vendor the first question is which ones do I need support for? The answer is "it all depends". I will take a simple approach and assume all you need to do is list (an already existing product) and then handle sales orders.

More bad news. Products are listed by ASIN. To list an existing product you need to be able to map your SKU to an Amazon ASIN.** The good news is that this task is trivial if you use the search feature of the Amazon Product Advertising API, the other API. It is not so easy using MWS.

For the basic stuff you only need to utilize a very few of the available sets of MWS APIs. The popular operations are a fairly short set:

  • To list a product all you need to do is submit a file via the Feeds API.
  • To alter inventory levels of a product all you need to do is submit a file via the Feeds API
  • To alter the price on a product all you need to do is submit a file via the Feeds API
  • To get a list of orders all you need to do is ask for a list of orders in a certain timeframe via the Orders API

Note that the above are not necessarily trivial operations. There are 14 different types of Feeds. The Feeds system works asynchronously. You submit a Feed file. Then you periodically check back to discover its processing progress status. You then attempt to recover from any individual product item issues encountered (since a feed file may contain hundreds of products). For orders you need to make sure to not process the same order more than once. Amazon does not care about which orders you already know about. It tells you about all orders in the timeframe you specified. It is up to you recognize new orders and ignore orders that you already know about. You need to deal with ensuring synchronization of data between Amazon and your back office systems.

This has been a very brief introduction to Amazon Marketplace Web Service. In future posts we will turn our attention to a Drupal perspective of Amazon's marketplace.

** This is not totally true for all products, Modern (after 2007) books have an ISBN that can be automagically mapped to an ASIN if they are popular enough to already exist in the specific Amazon marketplace you are interested in.