# sp-api-node

> 🛡 Fully typesafe Amazon Selling Partner API SDK for Node.js

Latest version **3.0.0** (published 2023-12-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install sp-api-node
pnpm add sp-api-node
yarn add sp-api-node
bun add sp-api-node
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2023-12-14 |
| First published | 2023-02-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 1.4 MB |
| Known vulnerabilities | 0 (+26 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2 |
| Author | ajmnz |
| Maintainers | ajmnz |
| Keywords | sp api, amazon sp api, amazon, selling partner api, selling partner, selling partner api sdk, node.js, sdk, typescript |

## Links

- npm: https://www.npmjs.com/package/sp-api-node
- Repository: https://github.com/ajmnz/selling-partner-api-node
- Homepage: https://github.com/ajmnz/selling-partner-api-node#readme
- Issues: https://github.com/ajmnz/selling-partner-api-node/issues
- npm.io page: https://npm.io/package/sp-api-node

## Dependencies (3)

- [axios](https://npm.io/package/axios.md) 0.27.2
- [form-data](https://npm.io/package/form-data.md) 4.0.0
- [aws4-axios](https://npm.io/package/aws4-axios.md) 2.4.9

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 3.0.0 (latest) — 2023-12-14
- 2.1.3 — 2023-11-08
- 2.1.2 — 2023-09-01
- 2.1.1 — 2023-06-22
- 2.1.0 — 2023-03-17
- 2.0.1 — 2023-03-17
- 2.0.0 — 2023-03-17
- 1.0.10 — 2023-03-16
- 1.0.9 — 2023-02-16
- 1.0.8 — 2023-02-16
- 1.0.7 — 2023-02-16
- 1.0.6 — 2023-02-15
- 1.0.5 — 2023-02-07
- 1.0.4 — 2023-02-07
- 1.0.3 — 2023-02-06
- … 2 more at https://npm.io/package/sp-api-node/versions

## README

<h1 align="center">Amazon Selling Partner API SDK</h1>
<p align="center">Fully typesafe Amazon Selling Partner API SDK for Node.js</p>
<div align="center">
  <a href="https://www.npmjs.com/package/sp-api-node">NPM</a>
</div>

<hr>

Some of the features

- 🛡 Fully typesafe with Amazon official definitions
- 🔄 Auto-updated with the latest model changes
- ⚡️ Auto-retrying requests when rate limited
- ⚔️ Authentication out of the box

## Installation

```sh
yarn add sp-api-node
# or with npm
npm install sp-api-node
```

## Before starting

In order to use the Selling Partner API, you need to register as a developer and register your application. Follow [Amazon's docs](https://developer-docs.amazon.com/sp-api/docs) on getting started with the Selling Partner API and obtaining a refresh token for your application.

### Authentication

This SDK handles authentication for you and takes care of both acquiring an access token and assuming the role via STS, as well as keeping the credentials refreshed. The client expects the following credentials:

- **Client ID**: See [viewing your application information and credentials](https://developer-docs.amazon.com/sp-api/docs/viewing-your-application-information-and-credentials)
- **Client Secret**: See [viewing your application information and credentials](https://developer-docs.amazon.com/sp-api/docs/viewing-your-application-information-and-credentials)
- **Role ARN**: See [creating and configuring IAM policies and entities](https://developer-docs.amazon.com/sp-api/docs/creating-and-configuring-iam-policies-and-entities)
- **Access Key**: See [creating and configuring IAM policies and entities](https://developer-docs.amazon.com/sp-api/docs/creating-and-configuring-iam-policies-and-entities)
- **Secret Key**: See [creating and configuring IAM policies and entities](https://developer-docs.amazon.com/sp-api/docs/creating-and-configuring-iam-policies-and-entities)
- **Refresh Token**: See [self authorization](https://developer-docs.amazon.com/sp-api/docs/self-authorization)
- **Role Session Name** (optional): For STS when assuming role. Default is `sp-api-node`.

## Usage

### Client options

| option                        | description                                                                                                                     | required | default |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| `region`                      | The region for the Selling Partner API (see [SP-API Endpoints](https://developer-docs.amazon.com/sp-api/docs/sp-api-endpoints)) | yes      | -       |
| `debug`                       | Log additional information like requests, authorization triggers, rate-limits, etc.                                             | no       | `false` |
| `handleRateLimits`            | If the client should intercept rate-limited requests and wait the appropriate time before retrying the request                  | no       | `true`  |
| `defaultRateLimitWaitSeconds` | How many seconds to wait by default if a request is rate limited and the client doesn't have information about the restore rate | no       | 60      |
| `credentials`                 | Credentials for calling the SP API (see [Authentication](#authentication))                                                      | yes      | -       |

### Calling the API

Import the client

```ts
import SellingPartner from "sp-api-node";
```

Create a new instance

```ts
const sp = new SellingPartner({
  region: "eu-west-1",
  credentials: {
    clientId: "amzn1.application-oa2-client.example",
    clientSecret: "050e346ef80574b4c3example",
    roleArn: "arn:aws:iam:3513513:role/SP-API-Example-Role",
    accessKey: "AKIAU420PEXAMPLE",
    secretKey: "53fac/51767+CJCo4/9aGexample",
    refreshToken: "Atzr|Ra55Kfgu-_...B03lexample",
    roleSessionName: "sp-api-node",
  },
});
```

Now all APIs are available as properties from the instance you just created. APIs that have only one version are accessible directly, while the ones that have multiple versions are accessible via `theApi.vVersion.theMethod()`.

```ts
// Single version

const participations = await sp.sellers.getMarketplaceParticipations();

// With multiple versions

const item = await sp.catalogItems.v0.getCatalogItem("my-asin", {
  MarketplaceId: "my-mkt-id",
});
```

### Accessing types for each endpoint

If you any of the types of a specific endpoint, you can import them through their dedicated path at `sp-api-node/<api>/<version?>`.

```ts
import type { Marketplace } from "sp-api-node/sellers";
import type { Order, OrderItem } from "sp-api-node/orders/v0";
```

### Handling rate limits

This SDK automatically handles rate limits and waits for the necessary amount of time by reading the `x-amzn-RateLimit-Limit` header. See [Usage Plans and Rate Limits in the SP-API](https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits-in-the-sp-api).

When Amazon replies with a `QuotaExceeded` error, the client will determine how many seconds are left before being able to retry the request without being rate-limited and stop execution for that amount of time.

If you want to prevent this type of behavior and have the client throw the `QuotaExceeded` error instead of waiting, pass `handleRateLimits: false` to the client constructor.

### TypeScript support

This client is fully written in TypeScript, by transforming the Amazon OpenAPI models into TypeScript definitions using the amazing [acacode/swagger-typescript-api](https://github.com/acacode/swagger-typescript-api) library.

### Getting the latest model updates

A Github Action runs every 30 minutes and gets the latest models from [amzn/selling-partner-api-models](https://github.com/amzn/selling-partner-api-models). If there's any changes in the generated client, updates will be pushed a new version will be released ensuring we always work with the latest models.

## License

MIT

---
_Source: https://npm.io/package/sp-api-node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._