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
