In part one and part two of this blog series, we covered order polling, shipping acknowledgement, and returns. These two blog posts covered the basics for integrating an Order Management System (OMS) with Amazon.
Let’s finish this blog series by talking about Amazon’s lack of a testing environment and why taxes were a major pain point for our integration. This post covers how we dealt with both of these issues and ensured a robust implementation.
Our OMS records the city and state taxes separately. The Amazon Order API only reports an item’s total tax in the ItemTax field of the ListOrderItems endpoint. However, Amazon does publish the breakdown in their Order Report, which is another feed that is available through the Feed API. However, as the documentation points out, the Feed API is more appropriate for bulk order processing, while the Order API is adept at handling orders in real-time.
This was our dilemma. In order to obtain the breakdown, we would have to sacrifice real-time processing. Hopefully Amazon will resolve this issue in the future by including this breakdown in the Order’s API.
For now, we implemented an integration with both methods. Although this approach did require extra work, this allowed our system to both process orders in real-time while avoiding the tax breakdown limitation of the Order API.
Once we had an integration set up with the various Amazon APIs, we needed to test our implementation. We quickly realized that Amazon does not have a testing environment.
We should discuss what Amazon does have to clarify what we mean. Amazon is able to put an account into staging mode, which disables all products from being visible and purchased through www.amazon.com. While in this mode, products will only be visible through mt.amazon.com, which requires credentials that an Amazon representative can supply.
However, regardless of the mode of the account, all orders placed through Amazon’s system are considered live orders. The credit card submitted with the order will be charged for the full price of the item and shipping costs. Furthermore, that order will permanently exist in the order history of the account.
The lack of a true testing environment is troubling for several reasons:
Every test order costs money.
Orders created for testing exist in the production environment.
Testing future changes requires placing orders through the production account.
Test environments need production credentials.
Amazon suggests that the price of the item and shipping charge should be set to $1.00 while placing test orders through their system. This minimizes our complaint with the first issue, but if your application doesn’t report to Amazon that the order was shipped in a timely manner, the order can drastically hurt the account’s rating before a real order has been placed.
There are several ways to proceed at this point:
Option 1: Leave our development and production environments connected to the same Amazon account. This would require differentiating test orders from production orders in some arbitrary way, and it doesn’t solve any of the listed issues.
Option 2: Create a separate account just for testing. We do not suggest going this route because Amazon’s terms of service do not allow a user to have multiple accounts.
Option 3: Create a test harness that mimics Amazon’s functionality.
None of these options are optimal for various reasons. Ultimately, we recommended setting up a test harness because it enabled our testing environments to be isolated and mitigated the issues listed above.
There are plenty of ways to implement a test harness. We decided to embed a module into an existing application. The module contained endpoints that mimic Amazon’s Order and Feed API. The test harness is able to place mock orders through our system, which enabled us to create repeatable test scenarios.
The following is a list of scenarios that were relevant for our integration:
Order item paging
State naming variations (e.g., PA vs. Pennsylvania)
Missing phone number
Multiple items with a duplicate SKU
Address line 2 populated instead of Address line 1
Scenario two and three tested our implementation for handling Amazon’s paging mechanism. These tests involved returning a message from the test harness that included a token, which would be used to poll for additional orders or items. The rest of the tests were scenarios around handling various input supplied by a customer on Amazon.com.
These example scenarios were relevant for us. There may be additional scenarios that need to be tested if supporting gift wrapping or promotions is required.
Lastly, we would like to commend Amazon’s MWS Scratchpad. It’s a tool that Amazon provides that has a simple UI for building and submitting requests to any of their APIs. It allowed us to quickly and easily test different input and then make the corresponding changes in our code. The Scratchpad removed much of the burden of formatting input, attaching proper headers and timestamps, and creating valid request signatures.
We leveraged the Scratchpad throughout development. It served as a great tool when we were getting our feet wet with the initial API calls and also helped immensely during the endgame, when we were debugging last-minute issues.
This post covered how we dealt with a limitation of Amazon’s Order API and how we tested our implementation. If you haven’t read the first or second posts in this series, go check them out now. Hopefully, these posts can help your implementation or help you make a decision about integrating with Amazon.