sp-api-node
v3.0.0
Published
🛡 Fully typesafe Amazon Selling Partner API SDK for Node.js
Downloads
581
Maintainers
Readme
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
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 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
- Client Secret: See viewing your application information and credentials
- Role ARN: See creating and configuring IAM policies and entities
- Access Key: See creating and configuring IAM policies and entities
- Secret Key: See creating and configuring IAM policies and entities
- Refresh Token: See 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) | 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) | yes | - |
Calling the API
Import the client
import SellingPartner from "sp-api-node";
Create a new instance
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()
.
// 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?>
.
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.
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 library.
Getting the latest model updates
A Github Action runs every 30 minutes and gets the latest models from 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