Amazon SP-API Roles Demystified

Since my last story, I discovered that I’m not the only one in this land of tears of Amazon new SP-API (Selling Partner APIs). In fact, even if it was cristal clear for me how to authenticate to these new APIs, I couldn’t do what I expected to be able to do reading Amzon migration guidelines.

Follow me in this new travel into this new floor of the SP-API inferno. This time we are going to dive deeper into SP-API roles.

*Bling Blong*
If you want to join my Whatsapp group dedicated to Amazon SP-API developers, follow this link. No fees, no plans. Just and old-school community!
*Bling Blong*

First of all, give a look to the official Amazon documentation on SP-API roles. As you can see there is a list of available roles that you, as a developer, can have on your Seller Central — Developer Central. These roles are:

• Product Listing
• Pricing
• Inventory and Order Management
• Amazon Fulfillment
• Buyer Communication
• Buyer Solicitation
• Finance and Accounting
• Selling Partner Insights
• Direct-to-Consumer Shipping
• Tax Invoicing
• Tax Remittance

Those who have the name in bold are restricted. This means that those roles enable you as a Developer to access to PII (personal identifiable informations) and, because of that, you will be required to provide Amazon with additional informations and documentation on how you treat Amazon’s data.

Developer Roles

Now, you will find roles that you are enabled to by entering into the Developer Central (Seller Central > Partner Network > Develop apps) and clicking on the “Your Developer Profile” link on the top of the page.

By entering into that page, you will your roles under the “Roles” section.

In this case, you can see that our Developer Profile is enabled for all the roles, even the restricted ones. If you need some role, you will have to check them and save your Devleoper Profile. A case with the Amaozn Developer support will be automatically opened and, if you are luck enough, you will receive an answer in few weeks and possibily a positive one. There is a chance that they will deny your roles. Unfortunately this is completely out of your and mine control and I cannot tell you how difficult it has been for us to be enabled for every role. I’ll explain it in the appendix of this story.

Client Roles

Now here comes the most confusing part, at least for me. Even if your developer is enabled for all the roles, you might find that your application doesn’t work for the operations you need to do. And this was driving me crazy (even if, after few months, I discovered that this wasn’t the only reason, check appendix).

Yes, because you will need to enable those roles on your Client as well.

Let me get clear on this. Suppose that you discovered that you were missing the “Tax Invoicing” role on your Developer Profile. You checked it, and sent your profile to Amazon in order to be reviewed. After that, you were granted that role. Well, that’s not enough.

You will have to enter into your Client (application) entries (by clicking on the “Edit App” button) and enable that role on the app as well.

Consider that if your application listing is under review, you won’t be able to edit it. So you will have to wait Amazon to approve your app listing and then re-edit it, in order to add the missing roles.

After your entered the app listing page, you will see a “Roles” section, where you will need to check your needed roles.

Remember to save, and be patient. It will take you few weeks (they say 10 business days, but in my experience it may took even a month) to have the app listing approved.

That’s not all

I told you that this was an inferno. There is just one last step to accomplish in order to close the circle (and finally breath again). All the refresh token you have, are linked to the roles that were enabled on your app when users granted access to their Seller Account.

This means that, if a user granted access to your app when the “Tax Invoicing” role was not enabled (even just on the app page), the token you have is not enabled to access “Tax Invoicing” related applications, even if your app has been accepted and published.

The only solution? Ask your users to grant access to your application again. And if you are wondering, no, there is no way to understand which roles is a token enabled to. This, in my opinion, will be a total hell in the next future, when Amazon will probably enable new roles and you will find yourself having mixed tokens with mixed granted roles.

Let’s summarize

If you, like me, had problems in accessing PII, for example when downloading orders from Amazon, you have to perform three checks:

1. Check that your Developer Profile is enabled for the “Tax Invoicing” role (or the roles that you will need for your case).
2. Check that your Application Listing Page is enabled for the same roles.
3. Ask your user to grant your application again, in order for you to receive a fresh, new and hopefully granted token that will allow you to perform what you need.

Remember that step 1 and 2 requires manual checks from Amazon and each of them may require months to be completed.

Hope that this clarifies every aspect of Amazon SP-API roles for you as well.

Thanks for reading.
Marco

Appendix

Our case was even worse, because Amazon — few years ago — deliberately deleted our Seller Central account, linked to our main application. After a lot of problems and NO SUPPORT at all from Amazon side, we discovered that we had to create a new Seller Central account, a new application and pass the whole certification again.

In the meantime we were audited by Deloitte, on our respect of both Amazon AUP (Acceptable Use Policy) and DPP (Data Protection Policy). So the crazy thing was that we were audited succesfully, but our (new) application didn’t have the roles to access PII. I was really getting mad.

An additional issue was related to the fact that, since we have two apps now (one linked to an unexisting Seller Central account, and one linked to our new Seller Central Account), we cannot migrate our old MWS tokens to the new SP-API tokens. This is caused to the fact that we are not able to have SP-API keys for our old app, since we don’t have access to our old Seller Central account anymore. This will require us to ask our customers to reauthenticate in the next future and finally we will be able to give our old application a fond farewell.

In conclusion, I cannot tell you — if you are a MWS developer — if your MWS tokens, migrated to SP-API tokens will be enabled for which roles, because I couldn’t perform this operation.