https://github.com/bizon/selling-partner-api-sdk
A modularized SDK library for Amazon Selling Partner API (fully typed in TypeScript)
https://github.com/bizon/selling-partner-api-sdk
amazon amazon-marketplace bizon brand-analytics nodejs retail-analytics sdk sellercentral typescript vendorcentral
Last synced: 15 days ago
JSON representation
A modularized SDK library for Amazon Selling Partner API (fully typed in TypeScript)
- Host: GitHub
- URL: https://github.com/bizon/selling-partner-api-sdk
- Owner: bizon
- License: mit
- Created: 2021-05-07T12:13:48.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-28T11:29:57.000Z (over 1 year ago)
- Last Synced: 2025-03-28T12:28:52.600Z (over 1 year ago)
- Topics: amazon, amazon-marketplace, bizon, brand-analytics, nodejs, retail-analytics, sdk, sellercentral, typescript, vendorcentral
- Language: TypeScript
- Homepage: https://bizon.github.io/selling-partner-api-sdk/
- Size: 187 MB
- Stars: 40
- Watchers: 1
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-spapi - Bizon - partner-api-sdk?style=plastic&logoWidth=1) (Docs / Library)
README
# selling-partner-api-sdk
[](https://codecov.io/gh/bizon/selling-partner-api-sdk)
[](https://github.com/xojs/xo)
Modularized, fully-typed TypeScript SDK for the Amazon Selling Partner API (SP-API), with independently versioned clients regenerated daily.
[
](https://www.bizon.solutions?utm_source=github&utm_medium=readme&utm_campaign=selling-partner-api-sdk)
## CI
[](https://github.com/bizon/selling-partner-api-sdk/actions/workflows/codegen.yml)
[](https://github.com/bizon/selling-partner-api-sdk/actions/workflows/openapi-generator.yml)
[](https://github.com/bizon/selling-partner-api-sdk/actions/workflows/tests.yml)
[](https://github.com/bizon/selling-partner-api-sdk/actions/workflows/release.yml)
[](https://github.com/bizon/selling-partner-api-sdk/actions/workflows/docs.yml)
## Documentation
To learn more about the Selling Partner API, visit the [official Amazon documentation](https://developer-docs.amazon.com/sp-api/docs).
Also, see the [generated documentation](https://bizon.github.io/selling-partner-api-sdk/) 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](https://developer-docs.amazon.com/sp-api/docs/connecting-to-the-selling-partner-api))
### Installation
Install the authentication package and the API client(s) you need:
```sh
npm install @sp-api-sdk/auth @sp-api-sdk/orders-api-2026-01-01
```
### Usage
```typescript
import {getMarketplaceByCode} from '@bizon/amazon-ids'
import {SellingPartnerApiAuth} from '@sp-api-sdk/auth'
import {OrdersApiClient} from '@sp-api-sdk/orders-api-2026-01-01'
const de = getMarketplaceByCode('de')!
// `clientId` and `clientSecret` default to the `LWA_CLIENT_ID` and
// `LWA_CLIENT_SECRET` environment variables.
const auth = new SellingPartnerApiAuth({
refreshToken: await getRefreshTokenForSeller(sellerId),
})
const client = new OrdersApiClient({
auth,
region: 'eu',
})
const {data} = await client.searchOrders({
marketplaceIds: [de.id],
createdAfter: '2026-01-01T00:00:00Z',
})
```
> Marketplace identifiers are not part of this SDK. The examples resolve them with
> [`@bizon/amazon-ids`](https://github.com/bizon/amazon-ids) (`npm install @bizon/amazon-ids`), a small
> package mapping country codes and domains to Amazon marketplaces.
### Configuration
The `ClientConfiguration` object supports the following options:
| Option | Type | Required | Description |
| --------------------- | ----------------------- | -------- | ----------------------------------------------------------------- |
| `auth` | `SellingPartnerApiAuth` | Yes | Authentication instance (see [`@sp-api-sdk/auth`](packages/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:
```javascript
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](https://github.com/hg-pyun/axios-logger):
```javascript
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](https://github.com/hg-pyun/axios-logger#options).
By default, `request` and `response` loggers use `console.info`, and the `error` logger uses `console.error`.
## Packages
- [auth](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/packages/auth): Authentication helpers for the Selling Partner API.
- [common](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/packages/common): Common utilities for the SDK.
- [schemas](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/packages/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:
- [amazon-warehousing-and-distribution-api-2024-05-09](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/amazon-warehousing-and-distribution-api-2024-05-09)
- [aplus-content-api-2020-11-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/aplus-content-api-2020-11-01)
- [application-integrations-api-2024-04-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/application-integrations-api-2024-04-01)
- [application-management-api-2023-11-30](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/application-management-api-2023-11-30)
- [catalog-items-api-2020-12-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/catalog-items-api-2020-12-01)
- [catalog-items-api-2022-04-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/catalog-items-api-2022-04-01)
- [catalog-items-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/catalog-items-api-v0)
- [customer-feedback-api-2024-06-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/customer-feedback-api-2024-06-01)
- [data-kiosk-api-2023-11-15](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/data-kiosk-api-2023-11-15)
- [delivery-by-amazon-delivery-shipment-invoice-v2022-07-01-api-2022-07-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/delivery-by-amazon-delivery-shipment-invoice-v2022-07-01-api-2022-07-01)
- [easy-ship-api-2022-03-23](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/easy-ship-api-2022-03-23)
- [external-fulfillment-inventory-api-2024-09-11](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/external-fulfillment-inventory-api-2024-09-11)
- [external-fulfillment-returns-api-2024-09-11](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/external-fulfillment-returns-api-2024-09-11)
- [external-fulfillment-shipments-api-2024-09-11](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/external-fulfillment-shipments-api-2024-09-11)
- [fba-inbound-eligibility-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/fba-inbound-eligibility-api-v1)
- [fba-inventory-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/fba-inventory-api-v1)
- [feeds-api-2021-06-30](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/feeds-api-2021-06-30)
- [finances-api-2024-06-19](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/finances-api-2024-06-19)
- [finances-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/finances-api-v0)
- [finances-transfers-api-2024-06-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/finances-transfers-api-2024-06-01)
- [fulfillment-inbound-api-2024-03-20](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/fulfillment-inbound-api-2024-03-20)
- [fulfillment-inbound-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/fulfillment-inbound-api-v0)
- [fulfillment-outbound-api-2020-07-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/fulfillment-outbound-api-2020-07-01)
- [invoices-api-2024-06-19](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/invoices-api-2024-06-19)
- [listings-items-api-2020-09-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/listings-items-api-2020-09-01)
- [listings-items-api-2021-08-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/listings-items-api-2021-08-01)
- [listings-restrictions-api-2021-08-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/listings-restrictions-api-2021-08-01)
- [merchant-fulfillment-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/merchant-fulfillment-api-v0)
- [messaging-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/messaging-api-v1)
- [notifications-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/notifications-api-v1)
- [orders-api-2026-01-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/orders-api-2026-01-01)
- [orders-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/orders-api-v0) — contains deprecated operations
- [product-fees-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/product-fees-api-v0)
- [product-pricing-api-2022-05-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/product-pricing-api-2022-05-01)
- [product-pricing-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/product-pricing-api-v0)
- [product-type-definitions-api-2020-09-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/product-type-definitions-api-2020-09-01)
- [replenishment-api-2022-11-07](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/replenishment-api-2022-11-07)
- [reports-api-2021-06-30](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/reports-api-2021-06-30)
- [sales-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/sales-api-v1)
- [seller-wallet-api-2024-03-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/seller-wallet-api-2024-03-01)
- [sellers-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/sellers-api-v1)
- [services-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/services-api-v1)
- [shipment-invoicing-api-v0](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/shipment-invoicing-api-v0)
- [shipping-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/shipping-api-v1)
- [shipping-api-v2](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/shipping-api-v2)
- [solicitations-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/solicitations-api-v1)
- [supply-sources-api-2020-07-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/supply-sources-api-2020-07-01)
- [tokens-api-2021-03-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/tokens-api-2021-03-01)
- [uploads-api-2020-11-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/uploads-api-2020-11-01)
- [vehicles-api-2024-11-01](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vehicles-api-2024-11-01)
- [vendor-direct-fulfillment-inventory-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-inventory-api-v1)
- [vendor-direct-fulfillment-orders-api-2021-12-28](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-orders-api-2021-12-28)
- [vendor-direct-fulfillment-orders-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-orders-api-v1)
- [vendor-direct-fulfillment-payments-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-payments-api-v1)
- [vendor-direct-fulfillment-sandbox-test-data-api-2021-10-28](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-sandbox-test-data-api-2021-10-28)
- [vendor-direct-fulfillment-shipping-api-2021-12-28](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-shipping-api-2021-12-28)
- [vendor-direct-fulfillment-shipping-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-shipping-api-v1)
- [vendor-direct-fulfillment-transactions-api-2021-12-28](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-transactions-api-2021-12-28)
- [vendor-direct-fulfillment-transactions-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-direct-fulfillment-transactions-api-v1)
- [vendor-invoices-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-invoices-api-v1)
- [vendor-orders-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-orders-api-v1)
- [vendor-shipments-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-shipments-api-v1)
- [vendor-transaction-status-api-v1](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/clients/vendor-transaction-status-api-v1)
The API clients are automatically generated from the Swagger/OpenAPI models from [the official models repository](https://github.com/amzn/selling-partner-api-models).
[A code generation workflow](https://github.com/bizon/selling-partner-api-sdk/actions/workflows/codegen.yml) 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`](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/packages/schemas).
It exposes the JSON schemas as well as typescript types.
For example, if you need the JSON schema for Vendor inventory reports:
```js
import {Reports} from '@sp-api-sdk/schemas'
console.log(Reports.vendorInventoryReport)
```
If you need the typescript type:
```ts
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](https://www.github.com/bizon/selling-partner-api-sdk/tree/master/codegen) module.
Some of the source Open API models are invalid (see the [issues](https://github.com/amzn/selling-partner-api-models/issues) and [PRs](https://github.com/amzn/selling-partner-api-models/pulls) on the Amazon repository), so this SDK defines some patches to account for those errors.
Each patch files are [JSON Patches](http://jsonpatch.com/) operations (1 logical change per file).
### Active patches
You can browse all the active patches in the [patches directory](https://github.com/bizon/selling-partner-api-sdk/tree/master/codegen/patches).
## License
MIT
## Miscellaneous
```text
╚⊙ ⊙╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
```