Selling Partner API SDK for JavaScript

selling-partner-api-sdk

A modularized SDK library for Amazon Selling Partner API (fully typed in TypeScript)

CI

Documentation

To learn more about the Selling Partner API, visit the official Amazon documentation. Also, see the generated documentation for each API client.

Features

This SDK supports the following features:

Installing only the API clients you need, versioned independently.
Passing client configuration through environment variables.
Retrying rate-limited requests by respecting the documented rate-limits and possibly provided headers.
Logging (non-auth) API requests, responses and errors.
Passing restricted data tokens to API clients.
Fully typed TypeScript API with auto-generated models and type definitions.
Dual module output (CommonJS and ES Modules).
Sandbox mode for testing against Amazon's sandbox endpoints.
Multi-region support: North America (na), Europe (eu), and Far East (fe).

Getting Started

Prerequisites

Node.js 24 or later
Amazon Selling Partner API credentials (LWA credentials)

Installation

Install the authentication package and the API client(s) you need:

npm install @sp-api-sdk/auth @sp-api-sdk/orders-api-v0

Usage

import { SellingPartnerApiAuth } from "@sp-api-sdk/auth";
import { OrdersApiClient } from "@sp-api-sdk/orders-api-v0";

const auth = new SellingPartnerApiAuth({
  clientId: process.env.LWA_CLIENT_ID,
  clientSecret: process.env.LWA_CLIENT_SECRET,
  refreshToken: "Atzr|…",
});

const client = new OrdersApiClient({
  auth,
  region: "eu",
});

const { data: orders } = await client.getOrders({
  marketplaceIds: ["A1PA6795UKMFR9"],
  createdAfter: "2024-01-01T00:00:00Z",
});

Configuration

The ClientConfiguration object supports the following options:

Option	Type	Required	Description
`auth`	`SellingPartnerApiAuth`	Yes	Authentication instance (see `@sp-api-sdk/auth`)
`region`	`'na' \| 'eu' \| 'fe'`	Yes	Selling Partner API region
`sandbox`	`boolean`	No	Use sandbox endpoints (default: `false`)
`rateLimiting`	`object`	No	Rate limiting configuration (see below)
`logging`	`object`	No	Logging configuration (see below)
`restrictedDataToken`	`string`	No	Restricted Data Token for accessing PII
`userAgent`	`string`	No	Custom user-agent header

Rate Limiting

Enable automatic retry on rate-limited (HTTP 429) requests:

const client = new OrdersApiClient({
  auth,
  region: "eu",
  rateLimiting: {
    retry: true,
    onRetry: (retryInfo) => {
      console.log(retryInfo);
    },
  },
});

The retry delay is calculated from the x-amzn-ratelimit-limit response header when available, falling back to the documented rate limits for each endpoint.

Logging

Enable request/response/error logging via axios-logger:

const client = new OrdersApiClient({
  auth,
  region: "eu",
  logging: {
    request: true,
    response: true,
    error: true,
  },
});

Pass true to use default options, or an object to customize the axios-logger configuration. By default, request and response loggers use console.info, and the error logger uses console.error.

Packages

auth: Authentication helpers for the Selling Partner API.
common: Common utilities for the SDK.
schemas: JSON schemas and TypeScript types for notifications, reports and feeds.

Clients

This repository contains an API client for each of the available Selling Partner API version:

The API clients are automatically generated from the Swagger/OpenAPI models from the official models repository. A code generation workflow runs twice a day and will create a PR on this repository whenever there are changes to the models.

Schemas

The SDK exposes notifications, reports and feeds schemas through @sp-api-sdk/schemas.
It exposes the JSON schemas as well as typescript types.

For example, if you need the JSON schema for Vendor inventory reports:

import { Reports } from "@sp-api-sdk/schemas";

console.log(Reports.vendorInventoryReport);

If you need the typescript type:

import { Reports } from "@sp-api-sdk/schemas";

const report = (await getVendorInventoryReportData()) as Reports.VendorInventoryReport;

Code generation

To see the code generation process, see the codegen module.

Some of the source Open API models are invalid (see the issues and PRs on the Amazon repository), so this SDK defines some patches to account for those errors.

Each patch files are JSON Patches operations (1 logical change per file).

Active patches

You can browse all the active patches in the patches directory.

License

MIT

Miscellaneous

    ╚⊙ ⊙╝
  ╚═(███)═╝
 ╚═(███)═╝
╚═(███)═╝
 ╚═(███)═╝
  ╚═(███)═╝
   ╚═(███)═╝