How to access the Amazon Selling Partner API

Amazon just released their new Selling Partner API, the successor to Amazon MWS. It has a number of advantages over MWS, as I described in my last post. Now that the new API has been released (at long last), it's time to get access to it! It's not as simple a process as you might expect, if you're used to the ease of access of APIs like Stripe, Google, or Twitter. Let's dive into it.

At a high level, here's what you need to do:

1. Create a Seller Central account (or log into an existing one if you have it)
2. Complete your developer application from within Seller Central
3. Register your Selling Partner application, using AWS IAM and Seller Central

These all sound like simple tasks, but together they can end up being pretty time-consuming.

Create a Seller Central account

You need a Professional-level Amazon Seller account to develop Amazon Marketplace apps, whether you're creating a custom Marketplace application to use for your personal Amazon selling business, or making an app to sell on the Marketplace Appstore. Basically, if you want to make use of Amazon's seller APIs for any reason, you need to pay Amazon $39.99/mo for a Professional Seller account.

To be extra clear: once you have a Seller Central account, you will apply for a developer account from within your Seller Central account. So all Amazon Marketplace developers have Seller Central accounts, but not all Selling Partners (Amazon's term for their sellers) have developer accounts.

Creating your Professional seller account is a lengthy but straightforward process. You'll need a few things to complete it:

• Your business information. In addition to things like your address or business name, Amazon is going to ask for your business type. One of the options is “None, I am an individual.” If you're planning on using your Amazon seller account for anything other than selling extra stuff lying around your house, do not select that option! The correct business type for you will probably be “Privately owned business.”You'll also be asked for a “Company registration number.” I wasn't sure what this should be for a sole proprietorship in the US, so I emailed Amazon support, and they recommended entering the social security number of the business owner (i.e., me).
• Personal information. Your name, address, phone number, and citizenship status, as well as proof of identity (driver's license or passport number).
• Billing information. A credit card that will be used to pay for your Professional account ($39.99/mo).
• Tax information. Your SSN or Federal Tax ID (depending on your business type), and some other basic tax-related data.
• Bank account information. The bank account that money earned on Amazon should be deposited into.

Get started with your Seller Central application here. Your account might not get approved immediately after you complete the application (mine took about a day to process).

Complete your Developer Application in Seller Central

Once your Seller Central account is approved, you can apply for a Amazon Marketplace developer account! Go to sellercentral.amazon.com, then click Partner Network > Develop Apps.

Clicking Proceed to Developer Profile will land you on another hefty form with a few different sections. Contact Information is straightforward, so let's move on to Data Access.

The first dropdown asks whether you're planning to use the seller APIs to make applications for your own Seller account, or applications that will be distributed to other Selling Partners. This totally depends on your use case. If you're not planning on distributing the tools you make, choose the first option. Otherwise, choose the second.

If you're already a Marketplace Web Services (MWS) developer, put your developer ID in the next field. You can find your developer ID on the Partner Network > Develop Apps page.[[1]]

Next is a list of roles, each corresponding to a set of resources and operations that are available via the Selling Partner API. As noted on the application form, some of the roles grant access to Personally Identifiable Information (PII), so tighter security requirements are placed on them. I recommend not selecting any of these roles unless you absolutely need to—they will slow down the application process and require you to implement complex data security measures, and you can always request access to them later if necessary.

Amazon has a lot of rules about what you can and can't do with their data, even if it doesn't contain any PII. I read through the legal documents related to the SP API[[2]], and here are my big takeaways (disclaimer: IANAL).

• Don't share Amazon transaction information or PII with anyone unless it's essential for your app to function. Aggregating customer or Seller information across multiple Selling Partners in order to share that information with other parties is not allowed, unless sharing that data is required for a service you're providing that benefits the Seller whose data is being shared.
• Track and monitor the storage location(s) of all copies of Amazon transaction data and PII. Ensure that no one can access Amazon data without your knowledge. Amazon can audit how well you're doing this whenever they want.
• Maintain certain security standards when working with Amazon data…
  • A firewall should be used to block access to your Amazon data from unauthorized IPs.
  • Each person with access to Amazon data should have a unique user ID, and user accounts should be monitored for unusual activity.
  • Amazon data has to be encrypted when sent over a network (HTTPS works fine).
  • There should be a specific plan in place for handling security breaches.
• Aaand even stricter security standards when handling PII.
  • PII should be stored for the minimum amount of time necessary. Max 30 days.
  • There should be a policy in place for how developers handle PII, and you should keep an inventory of all software and hardware with access to PII.
  • All stored PII must be encrypted using AES-128, AES-256, or RSA with 2048-bit key size (or higher) encryption. PII cannot be stored in removable media or public cloud storage.
  • Everyone who needs to access PII should have the minimum level of access possible.
  • Security monitoring and logging has to be implemented, and all logs should be kept for at least 90 days.

Whew!

Now that we got through that, let's move on to the Use Cases section. This is highly dependent on what you plan to build, but in your answers, I recommend restating their questions…For some reason, they seem to react well to that. For example, when answering this prompt:

Describe the application or feature(s) you intend to build using the functionality in the requested roles.

Start your answer something like this:

The application we plan to build using the roles we selected above will…

The “correct” answers to the Security Controls questions should be apparent from what I wrote above about the policies around handling Amazon data. I recommend complying with their policies, because they can shut you down whenever they want if you don't.

Once you're done with the whole form, click Register. Then hurry up and wait! It could take Amazon anywhere from a few minutes to a few weeks to approve your application, but it will probably be somewhere in the middle. In the meantime, let's get started registering your (future) Selling Partner API application.

Registering your Selling Partner API application

The SP API documentation has a guide on how to do this, but I recommend that you set things up a little differently from what their instructions say. The 30,000ft view of the process looks like this:

1. Create an AWS account, if you don't have one already.
2. Create an IAM user that will eventually be connected to your Selling Partner API developer credentials.
3. Create an inline policy on the IAM user that grants the user access to the SP API (this is where I'm telling you to do something different from what Amazon's instructions say—I'll explain why below).
4. Register your new SP API application! (Your developer application has to be approved first.)

For steps 1 and 2, follow Amazon's guide, but stop before their Step 3. Amazon says to create an IAM policy and IAM role, attach the policy to the role, and then add an STS policy to your IAM user. But as discussed in this GitHub issue, that adds an extra (seemingly unnecessary) step to the SP API authentication process. We're going to set things up in a way that allows you to skip that STS step.

Once you've completed Step 2, navigate to the IAM user you just created by clicking on its username in the list of IAM users. Then to grant the user access to the SP API:

1. Click Add inline policy in the upper right
2. Select the JSON tab
3. Paste the following JSON into the editor:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "execute-api:Invoke",
               "Resource": "arn:aws:execute-api:*:*:*"
           }
       ]
   }
   

4. Click Review Policy, and name your policy (I called mine ExecuteSPAPI)
5. Click Create policy

Awesome—you're done configuring IAM. You can ignore steps 3-5 of Amazon's guide on registering your SP API application.

Once your developer application in Seller Central is approved, you can create an SP API application by following this part of the guide), with one small change: instead of filling in a role ARN when you create the SP API application in Seller Central, you'll fill in the ARN of the IAM user you created in Step 2.

Now that you have an SP API application, it's time to write some code! Check out this post to learn how to write your first SP API program with PHP, or this one to write it in Java.

If you want to get notified when I write a new post, you can subscribe here:

(I help Amazon sellers automate business processes using the Selling Partner API—if you’re interested in upgrading your selling infrastructure, shoot me an email at jesse@jesseevers.com.)

[[1]]: If you're registered in more than one marketplace (marketplaces include North America, Europe, Japan, and Australia), you should add your developer IDs for each of those marketplaces to the form field. To find each marketplace's developer ID, switch to a country in that marketplace by the top-center dropdown menu of marketplaces:

[[2]]: Read Amazon's Marketplace Developer Agreement, Acceptable Use Policy, and Data Protection Policy for the full story.

Changelog

• 7/26/2022: Fixed broken “sole proprietorship” link
• 9/15/2021: Updated “Apps & Services” to “Partner Network” when referring to Seller Central nav option
• 8/20/2021: Updated broken GitHub links.
• 3/3/2021: Updated explanation of Seller data aggregation rules.
• 12/28/2020: Switched from using an IAM role for authentication to using an IAM user, which removes the need for an STS token.