Amazon SP-API Client

1.2.1 verified Sat Apr 25 auth: no javascript

A comprehensive client library for the Amazon Selling Partner API (SP-API). Current version 1.2.1 provides automatic access token management, rate limiting, report downloading, feed uploading, and full TypeScript support. It replaces the legacy Amazon MWS API with modern authentication and endpoints. The library handles throttling internally and offers sandbox mode for testing. Release cadence is periodic, with breaking changes notable when upgrading from v0.x to v1.x.

Common errors

error Error: Cannot find module 'amazon-sp-api' ↓

cause Package not installed or import path wrong.

fix

Run 'npm install amazon-sp-api' and ensure the import statement is correct: import SellingPartner from 'amazon-sp-api'

error TypeError: SellingPartner is not a constructor ↓

cause Incorrect import: trying to import a named export instead of default.

fix

Use: import SellingPartner from 'amazon-sp-api' (no curly braces)

error Error: Missing required parameter 'refreshToken' ↓

cause Refresh token not provided in constructor config or environment variable.

fix

Set REFRESH_TOKEN environment variable or pass refreshToken in the config object. For grantless operations, set grantless: true.

error Error: Invalid region. Supported regions: NA, EU, FE ↓

cause Region code provided is not valid.

fix

Use one of: 'NA', 'EU', 'FE' (case-sensitive).

error Error: Endpoint 'xxx' not found ↓

cause The API endpoint name is misspelled or unsupported.

fix

Check the list of supported endpoints and their exact names. Use the endpoint name as defined by Amazon SP-API, e.g., 'sellers', 'catalogItems'.

Warnings

breaking Version 1.x introduces breaking changes from 0.x. See the breaking changes documentation in the GitHub repo. ↓

fix Upgrade to 1.x and update code per the migration guide.

deprecated The legacy MWS API endpoint is replaced by SP-API. Ensure you are using the new Selling Partner API. ↓

fix Migrate from MWS to SP-API.

gotcha Class name is 'SellingPartner' with uppercase 'P', not 'Sellingpartner' or 'SellingPartnerApi'. ↓

fix Use the correct class name: SellingPartner.

gotcha Access tokens are automatically managed; do not manually set access tokens. ↓

fix Let the library handle token refresh automatically via refreshToken.

gotcha Some operations may require grantless access; use the 'grantless' option in callAPI. ↓

fix Set grantless: true for operations that don't require a refresh token.

deprecated The 'restore_rate' feature is experimental and may change in future versions. ↓

fix Monitor library updates for changes to restore rate functionality.

gotcha Rate limit headers are read automatically; you may still encounter throttling if limits are exceeded. ↓

fix Enable rate limit retry in config to have the library automatically wait and retry on throttled requests.

Install

npm install amazon-sp-api

yarn add amazon-sp-api

pnpm add amazon-sp-api

Imports

default
wrong
```
const SellingPartner = require('amazon-sp-api')
```
correct
```
import SellingPartner from 'amazon-sp-api'
```
ESM default import. Use 'SellingPartner' (note uncommon capitalization) as the constructor.
SellingPartner
wrong
```
import { SellingPartner } from 'amazon-sp-api'
```
correct
```
import SellingPartner from 'amazon-sp-api'
```
This is a default export, not a named export. Named import will fail.
createClient
wrong
```
import { createClient } from 'amazon-sp-api'
```
correct
```
import SellingPartner from 'amazon-sp-api'
```
The main export is the SellingPartner class, not a factory function. Use 'new SellingPartner()'.

Quickstart

Initializes the client with credentials and region, then calls the getMarketplaceParticipations operation on the Sellers endpoint.

import SellingPartner from 'amazon-sp-api';

const sp = new SellingPartner({
  region: 'EU',
  refreshToken: process.env.REFRESH_TOKEN ?? '',
  credentials: {
    SELLING_PARTNER_APP_CLIENT_ID: process.env.CLIENT_ID ?? '',
    SELLING_PARTNER_APP_CLIENT_SECRET: process.env.CLIENT_SECRET ?? ''
  }
});

const res = await sp.callAPI({
  operation: 'getMarketplaceParticipations',
  endpoint: 'sellers'
});

console.log(res);