Amazon Seller Central Integration

Unfortunately there are several hidden/undocumented things you have to do to use the SOAP API. It is almost like Amazon feels they have to offer it, but don't really want anybody to use it.

After several painstaking days of working with the AIM, ENS, and SOAP API's, I finally have figured out what works and what doesn't, and have a working Java based interface to Seller Central through the Amazon ENS and SOAP API's.

Amazon Inventory Management (AIM) API

The AIM API is pretty straight forward, and tab-delimited flat-files are pretty easy to work with. After implementing the API it became glaringly clear that there were no entry points to update anything to do with orders. You could generate order reports, but that was it, so off to SOAP.

Later I did try to upload inventory using the AIM api, and got the standard error 6000 invalid template error for a file that I could upload manually with no problem at all. This seems to be a recurring thread on Amazon forums, but the answer is usually let me see your headers/request, and never seeem to identify the problem. I did find one post that said to use Marketplace instead of MarketplaceOnly if it wasnt a books feed to clear up this error (undocumented header), but that didn't change anything.

The inability to work with order flow meant I needed to resolve that first with the SOAP API, and only pursue the flat-files if necessary.

Amazon Event Notification Services (ENS) API

As of today, there is only one type of event I get from Amazon and that is the SSN events. You will only receive one SSN event per order placed, and will not receive any followup events at all.

The OrderReport XML format received in an SSN event is not the same as that defined in the OrderReport XSD provided for the SOAP API. For one the tag schema uses a lower-cased name like aaBb verses the AaBb format used in all their other messages.

There are several other tags/field differences. Since I could not find an proper XSD anywhere I wound up modifying the XML tags to use the AaBb style format and then tweaked a copy of the OrderReport.xsd file until it worked. It required a couple dozen new tags. I was able to validate the most recent 200 order messages without any errors. I would prefer the API XSD files, if I could find one..

Rumor has it that the Amazon desktop has some additional XSD schema files that it installs. I was not able to install it on any computer where you already may have installed Microsoft SQL Server. Even after repeated uninstalls of SQL Server and messing with the InstallShield files, etc. Pretty obnoxious for the Amazon developers to decide that the only version of SQL Server you should have is the one they want you to have, and that it can't figure out that it is already installed. I will find a clean system to install and check for the XSD files..

Anyhow, I can parse all the incoming orders at this time, and I have verified that my system has not lost a single order in the past 90 days.

Amazon Seller Central SOAP API

Total nightmare. There is documentation for the API that at first looks like it should be a breeze, but there are several things that are missing.

WSDL File

I have only been successful with Axis 1.4. Axis 2.0 and the wsimport from JDK 1.6 both fail to process the WSDL file. Also remember to modify the document style contants as per the documentation, I use the following sed snippet in my build script:

FILE=src/com/amazon/merchant/MerchantInterface_BindingStub.java sed 's/oper.setReturnClass/oper.setStyle(org.apache.axis.constants.Style.DOCUMENT);&/' $FILE > $FILE.tmp mv $FILE.tmp $FILE

Undocumetned Requests

You can make requests for flat-file responses verses xml responses. I found this by looking at the source code for the AMTU program. For the two get requests, I needed to make them as flat-file requests. Supposedly you can have your account switched to XML so they would be XML request/responses but I have not yet changed anything on my account. For example the _GET_ORDERS_DATA_ request would be _GET_FLAT_FILE_ORDERS_DATA_. The first produced no results, the latter gave me the reports.

I tried posting FLAT_FILE data, but never got a reasonable response, the status would go to submitted or processing, but never change. My routines for getting status reports were still not written, so i am not sure if any status reports were ever returned. I never ran AMTU, so sending non-xml through this interface may be a possibility, but thats not what I wanted anyhow.

XSD Files

The XSD files on the Amazon site are in two groups, and is more obvious when you look at the source for the links. There is a core set, and there is a product set.

There are two sets of the amzn-base, amzn-envelope files and they are different. You want all the XML files, but use the product set of amzn-? files.

One of the XSD files had an invalid link, but was easily corrected when looking at it compare to the other links.

There are a couple of schema's without links, e.g. ToysBaby, and the FulfillmentCenter ones. The missing xsd files are in the same directory on the server as the other one, just modify the file name.

I was then able to use the JAXB reference implementation to generate a complete Java package from the XSD files (jdk 1.6).

SOAP Attachments

There is no example of what goes in an attachment, or what is required to be a valid attachment. I checked the documentation, the forums, google, and never found an example file. Nor could I find any reference to what the parent tags would be for an attachment..

I finally created a form where I could just post arbitrary XML as an attachment and started looking at the error responses until I got a valid message to go through. Here is a valid payload:

<?xml version="1.0" encoding="UTF-8"?>
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
  <Header>
    <DocumentVersion>1.02</DocumentVersion>
    <MerchantIdentifier>M_MERCHANT_123</MerchantIdentifier>
  </Header>
  <MessageType>Inventory</MessageType>
  <Message>
    <MessageID>1</MessageID>
    <Inventory>
      <SKU>1000</SKU>
      <Quantity>2</Quantity>
      <FulfillmentLatency>1</FulfillmentLatency>
    </Inventory>
  </Message>
  </AmazonEnvelope>

This is similar to the first attachment I got to go through with success. Some things that are undocumented, but seem to be required and not set by the generated code. The bottomline is look at an error response and mimic the tags in your request. I started sending formatted XML to them since their error responses will give you a line/column number where a parse/validation error occured.

Once I had a valid message through I modifed my libraries to set the required fields in the JAXB generated classes before sending my request. I had to tweak the XML to add the namespace fields before sending the attachment XML.

Namespace

Sending <AmazonEnvelope> produced an error, so you may have to modify your XML generation. When I tried any variation other than what was shown in an error response, I got an error.

Header

The only reference I can find to this header anywhere is in the actual XML or the XSD file. I got an error when leaving out either the merchant identifier or the document version. I don't know if version 1.02 is a magic number or not, I just mimic'd what was in the error responses. Again, no reference anywhere to this field or the valid values.

MessageType

Again this is required, and not documented anyhwere other than the xsd files. You will have to set it manually, and the valid values can be found in the amzn-envelope.xsd file.

MessageID

Again required, and has to be manually set.

Summary

I am now able to send various message attachments with success, and hope that the integration issues are behind me. I have written XML interfaces to e-bay, PayPal, FedEX, UPS, USPS, hotels.com, and several other proprietary systems, and this one has taken the longest by far.

My time getting to the 'hello world' stage on this interface was measured in days vs minutes for pretty much every other system I have worked with. During this process I downloaded the Associates web interface api from Amazon Web Services, integrated it, and was making valid requests from my application in under 15 minutes.

I have contacted Amazon twice about XML api's, the first contact just sent me to the XSD files. The second time I talked to them on the phone and he had me contact a bus-dev guy that told me flat out Amazon only supports XML for third-party integrators and that I should go talk to channel advisor or equivelent. When I referenced the API documentation, etc., he just forwarded me back to technical support.

If I had the information provided on this page, I could have saved a ton of time, I would hope that Amazon looks at providing turn-key libraries in the future or at least updates their documentation.

I still have a work in progress and hope I don't run into anymore problems, my worst fear is that the lack of documenation warrants undocumented changes that could break the interface at any time..

Links to their developer support forums:

Developer Support Forums

This is a work in progress, so I may update these notes as I learn more about how this interface works.

Things That Still Don't Work

_POST_TEST_ORDERS_DATA_ - no entry point, legacy or account config? I was told by an Amazon employee this may be a legacy call from when they actually had a special test environment for XML developers..

There is a Listings object in the XSD files that combines all the Product attributes into a single request instead of posting the product, picture, inventory, and price separately, there is no SOAP entry point for this request, and the data type cant be sent in a product post.