Developing with The Amazon Selling Partner API (SP-API)
Important New API from Amazon Replaces Legacy MWS-API
In 2020, Amazon released their new Selling Partner API and stopped allowing new users for its predecessor, the MWS API. As of now, Amazon is recommending all users to migrate to the SP-API, but has not given end-of-life or sunset dates for users of the MWS-API. Developers creating integrations with Amazon should be aware of the new API as well as it’s strengths and weaknesses.
New SP-API is a key tool for Managing Orders, Product Pricing, Sales, and More
The Selling Partner API, referred to as the SP-API from here forward, covers all of the same bases as the MWS-API did including its operations for orders, product pricing, sales, and much more. It does, however, come with technical differences, some beneficial and some not, that are important to be aware of.
During our first time developing with the Selling Partner API, we ran into a few snags and found ourselves wishing we had a guide to help us along the way. We’re hoping that this article can help other first-time users avoid the same pitfalls.
General Guidelines for Setup
The setup process for the SP-API is thoroughly documented, but complex and potentially punishing. Be sure you keep the official developer guide open while you work through the steps and double-check each step as you go. We recommend keeping a notepad or text editor open as you go in order to write down the tedious number of keys, tokens, accounts, and secrets that you will need to reference during authentication.
The SP-API punishes any mistakes made along the way with its lack of detailed responses, making it nearly impossible to identify where you went wrong. On our first time through, we accidentally used a “User ARN” for a step that required a “Role ARN”. When we started to make API calls, the errors gave no indication of the source of the problem, which resulted in some headaches.
See below for the list of specific fields you will ultimately need to make your API calls, and jot them down as you go.
- LWA App Client ID
- LWA App Client Secret
- Refresh Token
- AWS Access Key
- AWS Secret
- Role ARN
Improvements and Restrictions in Comparison to the MWS-API
The SP-API certainly comes with technical improvements — a JSON-based REST API, a sandbox for test calls, OAuth 2.0 authorization, and Login With Amazon integration — but it also presents a few restrictions. Along with the more arduous setup, those in need of speedy operations will be disappointed to see tighter rate limits for certain use cases. As opposed to a global rate limit across all operations, each operation now has its own limit, which can be found in the official documentation.
Some of the SP-API integrations we’ve developed at Pell Software include a heavy number of calls to the Orders and Product Pricing APIs. If, for instance, you need to gather as much information as possible for a list of particular Amazon products (let’s say you need name, description, weight, offers, etc.), the different API limits can become obstacles to one another.
For example, to receive the above fields, you will have to call both the getCatalogItem and getItemOffers operations. The getItemOffers operation is limited to 5 calls per second, but the getCatlogItem operation is limited to 2. Therefore, to get the required data for a single product, you are now limited to 2 calls per second.
Example Usage of the Amazon SP-API
Once you have been approved as a developer, received all six of your credentials, and created your application following the developer guide, it’s time to actually make the API calls. This can of be done using any standard method, but you also have some options that can help streamline the process. For NodeJS developers, one option is the excellent “amazon-sp-api” NPM package which enables setup and testing without hassles using environmental variables and straight-forward configuration options. This package also includes more detailed responses, which should help with troubleshooting any issues.
You can use an NPM package such as Bottleneck to help with the aforementioned rate limits. See the setup code for the Bottleneck NPM package below:
Making Calls with the “amazon-sp-api” NPM Package
The NPM page does a nice job of walking you through the setup using your six unique credentials, and creating a variable for the SellingPartnerAPI class. See a sample of this code below:
Your next step is to choose the operation you’re looking to call from the documentation. In this example, let’s say we want to get all “New” item offers for a particular Amazon product. You can do so by implementing the following function into your code.
async function getItemOffers(asin) {
let itemOffers = await sellingPartner.callAPI({
operation: ‘getItemOffers’,
query: {
MarketplaceId: ‘{marketplace-id}’,
ItemType: ‘Asin’,
ItemCondition: ‘New’
},
path: {
Asin: asin
}
});
}As you can see, this function will be passed an ASIN (Amazon Stock Information Number – each Amazon product has one). It uses the operation, query, and path fields to route the request to the exact data you’re seeking:
Operation
The operation field is where you will put the operation — or endpoint — you wish to receive data from. We recommend copying the operation name directly from the official documentation, as the field is case-sensitive.
Query
This field is where you determine which Marketplace, ASIN, and any other Operation-specific details (in this case, ItemCondition) you need to make your call. The Marketplace field is the ID that Amazon has assigned to each Marketplace. These Marketplaces are separated by region and can be found on this list.
Path
Finally, the path field is where you will enter the identifier of the object you are receiving data on. This identifier will depend on the operation you’re using. For the getItemOffers operation, it uses an ASIN.
From here, you can call your function and return the results in whatever method suits your project. See below for a sample of the API response you might receive.
{
“ASIN”: “{asin}”,
“status”: “Success”,
“ItemCondition”: “New”,
“Identifier”: {
“MarketplaceId”: {your-marketplace-id},
“ItemCondition”: “New”,
“ASIN”: “{asin}”
},
“Summary”: {
“LowestPrices”: [
{
“condition”: “used”,
“fulfillmentChannel”: “Merchant”,
“LandedPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 18.3
},
“ListingPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 18.3
},
“Shipping”: {
“CurrencyCode”: “USD”,
“Amount”: 0
}
},
{
“condition”: “new”,
“fulfillmentChannel”: “Amazon”,
“LandedPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 34.99
},
“ListingPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 34.99
},
“Shipping”: {
“CurrencyCode”: “USD”,
“Amount”: 0
}
}
],
“BuyBoxPrices”: [
{
“condition”: “new”,
“LandedPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 34.99
},
“ListingPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 34.99
},
“Shipping”: {
“CurrencyCode”: “USD”,
“Amount”: 0
}
},
{
“condition”: “used”,
“LandedPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 28.74
},
“ListingPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 28.74
},
“Shipping”: {
“CurrencyCode”: “USD”,
“Amount”: 0
}
}
],
“NumberOfOffers”: [
{
“condition”: “used”,
“fulfillmentChannel”: “Merchant”,
“OfferCount”: 50
},
{
“condition”: “new”,
“fulfillmentChannel”: “Amazon”,
“OfferCount”: 4
},
{
“condition”: “collectible”,
“fulfillmentChannel”: “Merchant”,
“OfferCount”: 3
},
{
“condition”: “used”,
“fulfillmentChannel”: “Amazon”,
“OfferCount”: 10
},
{
“condition”: “new”,
“fulfillmentChannel”: “Merchant”,
“OfferCount”: 11
}
],
“BuyBoxEligibleOffers”: [
{
“condition”: “used”,
“fulfillmentChannel”: “Merchant”,
“OfferCount”: 35
}
],
“SalesRankings”: [
{
“ProductCategoryId”: “book_display_on_website”,
“Rank”: 9637
}
],
“ListPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 50
},
“TotalOfferCount”: 78
},
“Offers”: [
{
“Shipping”: {
“CurrencyCode”: “USD”,
“Amount”: 0
},
“ListingPrice”: {
“CurrencyCode”: “USD”,
“Amount”: 34.99
},
“ShippingTime”: {
“maximumHours”: 0,
“minimumHours”: 0,
“availabilityType”: “NOW”
},
“SellerFeedbackRating”: {
“FeedbackCount”: 387,
“SellerPositiveFeedbackRating”: 91
},
“PrimeInformation”: {
“IsPrime”: true,
“IsNationalPrime”: true
},
“SubCondition”: “new”,
“SellerId”: {your-seller-id},
“IsFeaturedMerchant”: true,
“IsBuyBoxWinner”: true,
“IsFulfilledByAmazon”: true
}
],
“marketplaceId”: {your-marketplace-id}
}References
For C#/.NET apps:
If your application is C#/.NET based, we have found success with Amazon’s official C# Selling Partner API Model.
General Information:
For more information or ideas on ways to use Amazon’s SP-API, visit their official page, or https://github.com/amzn/selling-partner-api-docs/tree/main/references
Tool for NodeJS Developers