Selling Partner API JavaScript Client

• Cross-platform
  • works in all modern browsers
  • works in Node.js, Deno and Bun
• Written in TypeScript
  • full typing coverage
  • typing based on the OpenAPI schemas provided by Amazon
• Lightweight
• Handles authentication
  • auto-refresh access token
• Handles rate limiting with custom backoff strategy
• Handles throttling
• Handles request signing (needs additional setup)
• Auto-retry (1 retry by default)
• Automatic response destructuring using destr
  • no need to manually parse response
  • falls back to raw response

Install

NPM:

npm install spapi

PNPM:

pnpm add spapi

Yarn:

yarn add spapi

Usage

Create a client instance

import { createClient } from "@hexrw/spapi"

const client = createClient({
    clientId: "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    clientSecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    refreshToken: "Atzr|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    region: "eu",
}

Make a request

// Example request - get a list of 'GET_MERCHANT_LISTINGS_ALL_DATA' reports
import { Marketplaces } from "@hexrw/spapi"

/*
 * Response is automatically typed based on the OpenAPI schema provided by Amazon.
 * It will also be automatically parsed and destructured using the correct format
 * falling back to plain text if needed.
 */
const { reports } = await client.get("/reports/2021-06-30/reports", {
    params: {
        // Query will be automatically URL encoded, joined and appended to the final URL
        query: {
            reportTypes: [ "GET_MERCHANT_LISTINGS_ALL_DATA" ], // case-sensitive
            marketplaceIds: [ Marketplaces.UK ],
            pageSize: 10,
            createdSince: new Date("2021-01-01").toISOString(), // ISO 8601
            processingStatuses: [ "DONE" ], // case-sensitive
        }
    }
})

Make a request using a helper method from the wrapper

Note: The wrapper doesn't offer full coverage of the SP-API. It's only meant to make common requests easier.

import { Marketplaces } from "@hexrw/spapi"

const orders = await client.getOrders({
    marketplaceIds: [ Marketplaces.UK ],
    pageSize: 10,
    createdAfter: "2021-01-01", // supports all common date formats
})

Current internal fetch client SP-API coverage

| API Reference | Version | Status | |-------------------------------------------------------------|------------|--------| | A+ Content Management API v2020-11-01 | 2020-11-01 | 🚧 | | Authorization API v1 | v1 | ✅ | | Catalog Items API v2022-04-01 | 2022-04-01 | ✅ | | Catalog Items API v2020-12-01 | 2020-12-01 | ❌ | | Catalog Items API v0 | v0 | ❌ | | Easy Ship API v2022-03-23 | 2022-03-23 | 🚧 | | FBA Inbound Eligibility API v1 | V1 | 🚧 | | FBA Inventory API v1 | V1 | 🚧 | | FBA Small and Light API v1 | v1 | 🚧 | | Feeds API v2021-06-30 | 2021-06-30 | 🚧 | | Feeds API v2020-09-04 | 2020-09-04 | ❌ | | Finances API v0 | v0 | ✅ | | Fulfillment Inbound API v0 | v0 | 🚧 | | Fulfillment Outbound API v2020-07-01 | 2020-07-01 | 🚧 | | Listings Items API v2021-08-01 | 2021-08-01 | ✅ | | Listings Items API v2020-09-01 | 2020-09-01 | ❌ | | Listing Restrictions API v2021-08-01 | 2021-08-01 | ✅ | | Merchant Fulfillment API v0 | v0 | 🚧 | | Messaging API v1 | v1 | 🚧 | | Notifications API v1 | v1 | ✅ | | Orders API v0 | v0 | ✅ | | Product Fees API v0 | v0 | ✅ | | Product Pricing API v0 | v0 | ✅ | | Product Pricing API v2022-05-01 | 2022-05-01 | ✅ | | Product Type Definitions API v2020-09-01 | 2020-09-01 | ❌ | | Replenishment API v2022-11-07 | 2022-11-07 | ❌ | | Reports API v2021-06-30 | 2021-06-30 | ✅ | | Reports API v2020-09-04 | 2020-09-04 | ❌ | | Sales API v1 | v1 | ✅ | | Sellers API v1 | v1 | ✅ | | Services API v1 | v1 | ✅ | | Shipment Invoicing API v0 | v0 | 🚧 | | Shipping API v1 | v1 | 🚧 | | Solicitations API v1 | v1 | 🚧 | | Tokens API v2021-03-01 | 2021-03-01 | ✅ | | Uploads API v2020-11-01 | 2020-11-01 | 🚧 | | Vendor Direct Fulfillment Inventory API v1 | v1 | 🚧 | | Vendor Direct Fulfillment Orders API v2021-12-28 | 2021-12-28 | 🚧 | | Vendor Direct Fulfillment Orders API v1 | v1 | ❌ | | Vendor Direct Fulfillment Payments API v1 | v1 | 🚧 | | Vendor Direct Fulfillment Sandbox Test Data API v2021-12-28 | 2021-12-28 | ❌ | | Vendor Direct Fulfillment Shipping API v2021-12-28 | 2021-12-28 | 🚧 | | Vendor Direct Fulfillment Shipping API v1 | v1 | ❌ | | Vendor Direct Fulfillment Transactions API v2021-12-28 | 2021-12-28 | 🚧 | | Vendor Direct Fulfillment Transactions API v1 | v1 | ❌ | | Vendor Retail Procurement Invoices API v1 | v1 | 🚧 | | Vendor Retail Procurement Orders API v1 | v1 | 🚧 | | Vendor Retail Procurement Shipments API v1 | v1 | 🚧 | | Vendor Retail Procurement Transaction Status API v1 | v1 | 🚧 |

Development

Scripts

// package.json
{
    // ...
    "scripts": {
        "test": "jest",
        "test:ts": "tsc --noEmit",
        "schema:generate": "openapi-typescript --redoc ../api/redocly.yaml",
        "schema:generate-joined": "openapi-typescript ../api/sp-api.yaml -o ./src/schemas/index.ts",
        "publish": "pnpm publish --access public",
        "build": "tsc ./src/index.ts --outDir ./dist"
    }
    // ...
}

Generate schemas

npm run schema:generate

Join schemas

npm run schema:generate-joined

Build

npm run build

Publish

npm run publish

License

MIT