Amazon Seller Support

Have you had a chance to explore Amazon MWS yet?

Amazon Marketplace Web Service (Amazon MWS) is a Web service API that can help Amazon sellers automate processes for listings, orders, payments, reports, and more.

Amazon listing, order, and payment data can be integrated into existing workflows so that selling on Amazon fits right in with your regular business practices.

The Amazon MWS portal has client libraries, comprehensive documentation, and lots more. Take a look around: https://developer.amazonservices.com

Don't miss the Frequently Asked Questions and do feel free to browse through the Community Forum to see what Amazon MWS users and developers are discussing.

If you like what you see when you explore the site, sign up before you leave by clicking the "Sign up for MWS" button on the home page.

New response elements in the MWS Orders API section

A number of sellers have been requesting that the Amazon Marketplace Web Service (Amazon MWS) Orders API section return the buyer’s name and e-mail address. The Amazon MWS team is happy to announce that we have heard your requests and have added those and other response elements to the Orders API section. If you have been using an order report from the Amazon MWS Reports API section to retrieve your customers’ names and anonymized e-mail addresses, you can now more easily retrieve this information using the Orders API section.

Here’s what we’ve added to the Order response element, returned by the ListOrders, ListOrdersByNextToken, and GetOrder operations:

• MarketplaceId. If you sell in multiple marketplaces, you can now identify the marketplace that your orders were placed in with the MarketplaceId response element.

• BuyerName. You can now associate the buyer’s name with the orders that the Orders API section returns.

• BuyerEmail. The Orders API section returns the buyer’s anonymized e-mail address, so you can communicate with your buyers and identify repeat buyers.

• ShipServiceLevelCategory. This response element indicates the type of shipping that a customer requested when they placed their order.

We’ve also added a new element to the OrderItem response element, returned by the ListOrderItems and ListOrderItemsByNextToken operations:

• GiftWrapLevel. You can now see the gift wrap level that a customer specified when they placed their order.

Also note that we increased the throttling limits for the Orders API section. The new throttling limits are as follows:

• The maximum request quota that the ListOrders and ListOrdersByNextToken operations share was increased from 4 to 6. The restore rate that the two operations share was increased from one request every 10 minutes to one request every 5 minutes.

• The maximum request quota that the ListOrderItems and ListOrderItemsByNextToken operations share was increased from 10 to 15. The restore rate that the two operations share was increased from one request every 12 seconds to one request every 6 seconds.

Label items one by one and include them in an inbound shipment

If your workflow calls for you to label items one by one and add them to one or more inbound shipments, you can do this by following the steps below:

1. Submit the CreateInboundShipmentPlan operation for a single item—the item that you want to label and ship.

If you have previously created a listing for this item, specify only the SellerSKU for the item.

OR

If have not yet created a listing for this item, specify the SellerSKU, ASIN, and Condition for the item.

Note: For many items, it is difficult to know the ASIN before creating a listing for it. For this reason, whenever possible you should create a listing for an item before submitting the CreateInboundShipmentPlan operation for that item.

The response elements include FulfillmentNetworkSKU, DestinationFulfillmentCenterId, and ShipmentId.

2. Use the FulfillmentNetworkSKU returned in Step 1 to create a label for your item, and then label the item.

3. Check the DestinationFulfillmentCenterId returned in Step 1 to determine which Amazon fulfillment center to ship the item to.

4. This step depends on whether an inbound shipment already exists for the destination of the item.

If this is the first item of a new inbound shipment, or if the FulfillmentNetworkSKU returned in Step 1 indicates an Amazon fulfillment center that is different from any existing inbound shipment that you have in progress, do the following:

• Submit the CreateInboundShipment operation to initiate a new inbound shipment, using the ShipmentId that was returned in Step 1.

OR

If you are adding this item to an existing inbound shipment, do the following:

• Identify the ShipmentId of an existing inbound shipment that has the same DestinationFulfillmentCenterId as the DestinationFulfillmentCenterId returned by the CreateInboundShipmentPlan operation in Step 1.

• Submit the UpdateInboundShipment operation using the ShipmentId identified in the preceding bullet, as well as the SellerSKU and QuantityShipped values for the item.

Create an FBA inbound shipment containing more than 200 items

Amazon recommends that you specify no more than 200 items (as defined by SellerSKU) when submitting the CreateInboundShipmentPlan operation. Given this limit, how do you create an inbound shipment with more than 200 items? Follow the guidelines below:

1. Divide your items into batches, with each batch containing 200 items (SellerSKU values) or fewer.
2. Submit the CreateInboundShipmentPlan operation for the first batch of items. For each inbound shipment plan that is returned, create a separate inbound shipment by submitting the CreateInboundShipment operation.
3. Submit the CreateInboundShipmentPlan operation for the second batch of items. If an inbound shipment plan is returned that matches an inbound shipment created in Step 2, (i.e. they have the same DestinationFulfillmentCenterId and LabelPrepType values), then add the items from that inbound shipment plan to the matching inbound shipment. Do this by submitting the UpdateInboundShipment operation. Otherwise, create a new inbound shipment by submitting the CreateInboundShipment operation.
4. Submit the CreateInboundShipmentPlan operation for each batch of items. Continue matching the returned inbound shipment plans with existing inbound shipments, adding items to existing inbound shipments (using the UpdateInboundShipment operation) when possible and creating new inbound shipments (using the CreateInboundShipment operation) when necessary.

The following is a hypothetical workflow that illustrates in detail how to create an inbound shipment containing more than 200 items. In the example below, the inbound shipment contains 500 items.

1. Submit the CreateInboundShipmentPlan operation for items 1 through 200.

    Suppose the following two inbound shipment plans are returned:

• Plan 1: 50 items, ShipmentId = FBAEX0001, DestinationFulfillmentCenterId = RNO1 LabelPrepType = NO_LABEL

• Plan 2: 150 items, ShipmentId = FBAEX0002, DestinationFulfillmentCenterId = PHX3, LabelPrepType = NO_LABEL

2. Submit the CreateInboundShipment operation twice to create the following two inbound shipments:

• Shipment FBAEX0001: 50 items

• Shipment FBAEX0002: 150 items

3. Submit the CreateInboundShipmentPlan operation for items 201 through 400.

    Suppose the following two inbound shipment plans are returned:

• Plan 3: 180 items, ShipmentId = FBAEX0003, DestinationFulfillmentCenterId = RNO1, LabelPrepType = NO_LABEL
• Plan 4: 20 items, ShipmentId = FBAEX0004, DestinationFulfillmentCenterId = RNO1, LabelPrepType = SELLER_LABEL

4. Submit the UpdateInboundShipment operation to add the 180 items from Plan 3 to shipment FBAEX0001, as Plan 3 and Plan 1 have identical DestinationFulfillmentCenterId and LabelPrepType  values.

5. Submit the CreateInboundShipment operation to create a new shipment FBAEX0004 for the 20 items in Plan 4, as the DestinationFulfillmentCenterId and LabelPrepType values of Plan 4 do not match those of any existing inbound shipments.

6. Submit the CreateInboundShipmentPlan operation for items 401 through 500.

    Suppose the following inbound shipment plan is returned:

• Plan 5: 100 items, ShipmentId: FBAEX0005, DestinationFulfillmentCenterId: PHX3, LabelPrepType: NO_LABEL.

7. Submit the UpdateInboundShipment operation to add the 100 items from Plan 5 to shipment FBAEX0002, as Plan 5 and Plan 2 have identical DestinationFulfillmentCenterId and LabelPrepType values.

The following three inbound shipments have been created:

• Shipment FBAEX0001: 50 + 180 items, DestinationFulfillmentCenterId = RNO1, LabelPrepType = NO_LABEL
• Shipment FBAEX0002: 150 + 100 items, DestinationFulfillmentCenterId = PHX3, LabelPrepType = NO_LABEL
• Shipment FBAEX0004: 20 items, DestinationFulfillmentCenterId = RNO1, LabelPrepType = SELLER_LABEL

The Sellers API section now available in North America

The MWS team is pleased to announce the North America public launch of the Sellers API section in Amazon Marketplace Web Service. Previously, Sellers and developers had to manually determine in which marketplaces a seller was registered as well as information about listing in each marketplace (language, currency, etc.). The new Sellers API allows in one operation the retrieval of all marketplaces that a seller can sell in along with additional information about those marketplaces and the seller's participation in those marketplaces.

 

Note that the Sellers API is for determining what marketplaces the seller who is submitting the request is registered in. You cannot use this API to determine what marketplace other sellers are in, just your own marketplaces. More details about the new API can be viewed on the Sellers API section page of the MWS Developer portal.

Marketplace and MarketplaceIdList parameters in the HTTP Request

The Marketplace parameter in the HTTP request has not been required for a while, but some folks are under the impression that the MarketplaceIdList parameter has taken its place. This isn't the case. The Marketplace parameter has been deprecated, so it is no longer part of the authentication process.

The MarketplaceIdList parameter is an optional parameter that is used with two operations, SubmitFeed and RequestReport. These two operations can take multiple marketplace Ids for the marketplaces that you sell in for a single request. Other operations, such as the GetReportRequestList operation, don't use this parameter so if you include it in the HTTP request, you will get an error (400 response code).

 

When working with multiple marketplaces, such as in the EU, you can specify several marketplaces that you sell in using the MarketplaceIdList parameter. For example:

 

&MarketplaceIdList.Id.1=A13V1IB3VIYZZH&MarketplaceIdList.Id.2=A1PA6795UKMFR9

 

In NA, you can specify your seller account and your Webstore, for example.

 

Just remember, you no longer need to include in the HTTP request the Marketplace parameter, and the MarketplaceIdList parameter is only used for the SubmitFeed and RequestReport operations.

Spreading out your Amazon MWS requests

Many of us work by the clock, and when the big hand is pointing skyward, that's when we do things. Meetings often start "on the hour" as do many forms of entertainment, programs, and services. But "on the hour" is not a good time to submit lots of requests to Amazon MWS. Because many of your neighbors are doing the exact same thing, when everyone submits requests at the same time, the service can be overwhelmed, affecting its availability.

 

Almost all web services have request rate limits, limits that prevent the service from being overwhelmed by requests. Amazon MWS enforces these limits through a technique called throttling, only allowing a certain rate of requests per operation from all users. Requests that exceed this limit are throttled, resulting in the operation failing with a response code of 503 (Service temporarily unavailable). So one thing you need to consider as a developer using Amazon MWS is when is the best time to submit your requests.

 

The few best practices for timing requests are these:

• Pick a random time to call Amazon MWS, not a predictable one such as at the top of the hour or even on the minute.
• For periodic requests, add a jitter (small random variance) to your wait time. So, for example, if you are calling a particular Amazon MWS operation at 10-minute intervals, with a jitter you would still call Amazon MWS six times an hour, but at random intervals varying from, say, 9 to 11 minutes. An initial request could be made at a random time, such as three minutes and 19 seconds after the hour, and then every 10 minutes with a 10% jitter.

 

Suppose you are submitting a request to list orders every 10 minutes for a large number of clients. You should stagger these requests so that all the requests are not submitted at once. This keeps the Amazon MWS web service from possibly being overwhelmed and allows other sellers to submit feeds or retrieve reports. Amazon Services periodically reviews the Amazon MWS web service availability and will loosen restrictions when appropriate. Sellers who spread out their requests over the day, reducing peak usage, can increase the service's availability and reduce the amount of throttling required to keep the service available.

 

Amazon MWS receives a big bursts of requests on the hour. If you spread these requests out over the hour and randomize when you submit your initial requests, everyone wins.