In part one of our Amazon MWS blog series, we walked through Amazon’s Orders API and how you can use it to process orders placed on Amazon. In this entry, we will discuss cancelling orders, submitting shipment notifications, and generating returns by integrating with the Feeds API. Specifically, we will use the OrderAcknowledgment, OrderFulfillment, and OrderAdjustment feeds. Amazon provides documentation on these feeds in the Selling on Amazon Guide to XML.
Typically, there are a few things you might want to do with an order after your system has received and consumed it, such as:
Cancel the order prior to fulfillment
Send a shipment notification to the customer (or back to Amazon in this case)
Accept/reject a return request
To notify Amazon of the result of any of the above actions, we need to send something to Amazon. Thankfully, Amazon offers a Feeds API, which allows sellers to programmatically construct and send feed messages to Amazon. Note that when we mention “feed messages,” we are referring to XML messages that Amazon will eventually consume.
Cancelling and Acknowledging Orders
The Order Acknowledgment feed gives sellers the ability to acknowledge receipt of orders from Amazon. In other words, by sending the Order Acknowledgment feed to Amazon with a status of “Success,” a seller can confirm that certain orders have been pulled into their order management system. This is not, however, a confirmation of shipment. To send shipment notifications we used the Order Fulfillment Feed (which we will address later).
Accelerate your transition to the cloud with our AWS expertise
In addition to acknowledging orders, the Order Acknowledgment feed can also cancel orders. By sending a feed with a status of “Failure,” sellers can cancel specific orders. You might want to cancel an order before fulfillment for several reasons, such as lack of inventory. Keep in mind that this operation will cancel the entire order, including all the items associated with it. To partially cancel an order, you should use the Order Adjustment feed (detailed below in “Approving Return Requests”).
Once your warehouse ships an order, you will want to notify the customer. With the Order Fulfillment feed, sellers can provide Amazon with shipment information, such as the tracking number and carrier name, for example. Using the Order Fulfillment feed is straightforward; send it to Amazon and the order will appear as “Shipped” to the customer. Simple!
Approving Return Requests
Handling returns was the single most headache-inducing task of our entire Amazon implementation. Amazon offers no way to programmatically notify sellers that a customer has requested a return; instead, Amazon sends an email to the seller. On top of that, there is no API to poll active return requests from Amazon, which ultimately means there is no automated way for sellers to react when a customer creates a return. Apparently, Amazon wants every return to be handled individually. As developers, however, we want to build a reliable solution that will do the same job, the same way, every time. To overcome this hurdle, we considered three approaches:
Automated: Build an email listener that would intercept Amazon’s emails and translate them into returns
Partially Automated: Develop a return creation tool that would allow a manager to input the return decision (and a few other required fields) and generate a return after receiving an email
Manual: Build nothing. Customer Service would approve all return requests and reach out to customers to complete the process
Most developers would probably agree that parsing an email is unreliable. If the email format changes even in the slightest, the entire return mechanism could break. We needed a robust solution that would deliver consistent results, and we knew our return volume would be very low (our current return rate was only a few percentage points). We did not want to offload all return processing to customer service, as this would be a large step backward for our application.
For these reasons, we decided to develop a return tool that generated returns with limited user input. The tool only required a manager to enter the quantity and reason for the return, and the system would handle creating a return and notifying Amazon. The solution was not ideal, but it would work consistently. To notify Amazon of approved returns, we used the Order Adjustment feed. With this feed, sellers can process returns and cancel individual items.
Submitting Feeds to Amazon
To submit feeds to Amazon, use the SubmitFeed operation of the Feeds API. The body of your submit feed request is the actual XML feed message, which, in this case, is the Order Acknowledgment, Order Fulfillment, or Order Adjustment feed.
Amazon provides an XML Schema Definition (XSD) file for each feed type. For Java, JAXB can be used to convert the XSDs into Java Classes. A URL to download each XSD is listed in their respective section in Amazon’s Selling on Amazon Guide to XML.
Avoiding Rate Limits
Because Amazon limits how often you can submit feeds, we implemented a simple strategy to ensure all of our feed messages were delivered successfully. We decided to save every feed message after it was generated, then gather and submit all of the messages that were created over a given timeframe. See below for a step-by-step example of our rate-limiting strategy:
Some event occurs that requires a notification to Amazon (e.g., we received an order, canceled an order, shipped an order, approved a return request, etc.).
The system generates a feed message, such as an Order Acknowledgement, with a status of “Success”.
The system saves the feed message in the database.
An automated process gathers all of the feed messages created over a specific timeframe, adds them all to a single SubmitFeed request, and finally submits the feeds to Amazon in one REST call.
We chose to send a SubmitFeed request to Amazon every 20 minutes; however, depending on the volume of orders you process and how quickly you want Amazon to receive your notifications, you might want to submit feeds more or less frequently.
We’ve covered everything you need to send notifications to Amazon. Stay tuned for the last entry in our blog series, “Ensuring a Robust Implementation,” which will cover how to test your Amazon integration despite the lack of an Amazon testing environment, including how we handled taxes.