Amazon selling partner API (SPAPI) — how to quickly and simply integrate with new API (Part 1)

SP-API

Hi, my name is Volodymyr, I am a software engineer interested in AWS, and integrations with MWS, SPAPI. This is my first story on Medium, and I would like to share with you quick and simple guide on how to start using the new Amazon selling partner API (SPA).

But before we start deep dive into AWS and MWS / SPA, let’s start with simple things.

My article is divided into several parts:

1. Why do you need an Amazon seller account
2. How to upgrade account to Developer
3. How to create your first application
4. How to create an AWS account, and manage user, roles, policies required to set up your new Amazon application.

In the official documentation, there is a lot of steps that can confuse you on start of developing your application. You need to understand a lot of abbreviation and technical stuff to start. In this article, I will try to describe what exactly you need, and what technical things you should understand to run you first application, also I will share with you some code with a working integration example.

For those who wants to start from official documentation, Amazon already provides detailed instructions that you can find here, also I will use steps from the official documentation in this guide too.

Why do you need an Amazon seller account?

One important thing that you should understand, is that to start developing you should have an Amazon developer seller account (Premium plan) that will cost you 40$ per month. After that, you will have the possibility to request an account upgrade to Developer type.

You can register your new Amazon seller account by this link (USA region), and after you pass registration and verification you can request an upgrade to a Developer account by this link.

How to upgrade the account to Developer?

Let’s look at the Developer form in detail.

Amazon developer profile form

You need to provide correct information about your organization, your contact information, website, contact email, etc…

The next steps in the application are the most important, and it is crucial to fill in all information correctly and add a lot of extra details about your project.

Amazon developer profile form

Be careful with the roles that you pick in form, as some of them can require extra security checks and compliance from Amazon. (Details explanation about each of the role, you can find here) you should select roles that you will use for 100 percents, in case if something changes with the time you can re-submit this form with new data.

Also, it is important to correctly describe your application from the perspective of features which will use selected roles. Explain in details how do you plan to use selected roles and what benefits does end-user get from your application.

And the last step is to pass security control.

Amazon developer profile form

Check the points which describe your application security practices (This is one of the important parts, as Amazon really cares how and where you collect / process and store seller information). After you finished, click Submit.

When you submit a Developer form you need to wait a short time (I had to wait for 2 hr) until Amazon checks and approves the application. You will get an email notification when everything will be ready.

How to create your first application?

To create a new application you just need to open Apps&Services -> Develop app, and click Add new application

App registration

In the API Type field, you need to select the type of API which you want to use, MWS is an old stable API provided by Amazon and SP API is a new REST API that Amazon announced in 2020. You can select MWS and SP API support if you plan to develop a universal application.

In this guide, I used SP API and MWS. When you select this option you will be required to provide extra details. In the next section, I will provide details on how to fill the form and where to find IAM ARN.

How to create an AWS account, and manage users, roles, policies required to set up your new Amazon application?

First of all, you need to create an AWS account (it’s free of charge, actions that you will perform inside the account also is free of charge), to create a new account click here.

Add a new user

After creation a new account, go to IAM, or click on this link, if you want to learn more about IAM users, please read this official docs.

1. In the navigation pane at left, click Users and then click Add user.
2. Type the user name for the new user. This is the sign-in name for AWS.
3. Select Programmatic access and then click Next: Permissions.
4. On the Set Permissions page, accept the defaults and click the Next: Tags
5. Tags are optional, you can skip this step
6. On the Review page, review the choices you have made. You can ignore the This user has no permissions warning. You will set permissions when you create an IAM role. When you are ready to proceed, click the Create user button.

The AWS access key ID for your new IAM user is displayed, click Show to view the AWS secret access key. To save the AWS access key, click Download .csv, and then save the file to a safe location.

Important: This is your only opportunity to view or download your AWS secret access key, which you will need to authenticate your calls to the Selling Partner API. Save the AWS access key ID and AWS secret access key in a safe and secure place. You will not have access to the AWS access key again after this step. If you lose your AWS secret access key you will need to create a new IAM user with its own new set of keys.

Click Close. In the User name column, click your new IAM user and make a note of the User ARN. You will need it when we start creating a new IAM role.

Create an IAM policy

More about IAM policies you can find here, if you have any question or need more details about this step, please leave the comment.

1. Navigate to IAM or open this link
2. In the navigation pane at left, click Policies. If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Click Get Started.
3. Click the Create policy button.
4. Click the JSON tab.
5. Paste the following code into the text box, replacing the existing code, and then click Review policy.

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

6. On the Review policy page, type a Name and a Description (optional) for the policy that you are creating. AWS recommends naming your IAM policy, SellingPartnerAPI.

7. Review the policy Summary to see the permissions that are granted by your policy, then click the Create policy button.

Your new IAM policy appears in the list.

Create an IAM role

You can find more information about IAM role here, create an IAM role that trusts the IAM user that you created

1. Navigate to IAM or open this link
2. In the navigation pane at left, click Roles and then click Create role button.
3. On the Create role page, click Another AWS account.
4. In the Account ID box, enter the account identifier for the AWS account in which you created your IAM user and click Next: Permissions. Where to find Account ID? In the navigation bar at the upper right, choose your user name and then choose My Security Credentials. The account number appears either under Account identifiers (if you are the root user) or under Account details (if you are an IAM user).
5. On the Attach permissions policies page, under Policy name, select the policy that you created.
6. Add tags (you can skip this and move to Next: Review)
7. On the Create role page, enter a role name in the Role name box, an optional role description in the Role description box, and then click the Create role button.
8. Under Role name, click the name of your new role.
9. Save your role ARN (Super important!)

Add an AWS Security Token Service policy to your IAM user

More information about AWS STS you can find here

From the official documentation:

Adding an AWS Security Token Service (AWS STS) policy to your IAM user enables you to request temporary AWS access keys that you can use to authenticate your requests to the Selling Partner API. These credentials expire after a set period of time, helping you to control access to your AWS resources.

1. Navigate to IAM or open this link
2. In the navigation pane at left, click Users and then choose the user you created at beginning of this guide
3. On the Permissions tab, click Add inline policy.
4. On the Create policy page, click Choose a service.
5. Click the STS service.
6. Click the arrow next to Write to expand it.
7. Select AssumeRole.
8. Click the arrow next to Resources to expand it, and then click Add ARN.
9. In the Add ARN(s) dialog box, enter the role ARN that you save from step Create an IAM role
10. On the Review policy page, enter a name for your policy in the Name box. Review the choices you have made. If you are ready to proceed, click the Create policy button.

In order to complete application creation, you need to copy and paste your newly created Role ARN into IAM ARN field.

After that select Roles that you plan to use in your application. If you plan to use OAuth you need to provide OAuth Login URI and OAuth Redirect URI.

Click Save and Exit.

In the next article, I will explain in detail how to use the new SPAPI with NodeJS, share with you a tiny library that helps you easily handle API requests encryption and processing. Thank you for your time, hope it was helpfull.