@hexrw/spapi

1.0.0-alpha.6 • Public • Published

Selling Partner API JavaScript Client

  • Cross-platform
    • works in all modern browsers
    • works in Node.js, Deno and Bun
  • Written in TypeScript
  • 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

Expand
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

Package Sidebar

Install

npm i @hexrw/spapi

Weekly Downloads

1

Version

1.0.0-alpha.6

License

MIT

Unpacked Size

1.78 MB

Total Files

30

Last publish

Collaborators

  • hexrw