@sp-api-sdk/common

@sp-api-sdk/common

Amazon Selling Partner API common package

Installing

npm install @sp-api-sdk/common

Note: You typically do not need to install this package directly. It is automatically included as a dependency of every API client package.

Overview

This package provides the shared infrastructure used by all API client packages:

• Axios instance factory with authentication, rate limiting, logging, and error handling
• Region configuration for NA, EU, and FE endpoints (production and sandbox)
• Error handling with SellingPartnerApiError

Client Configuration

The ClientConfiguration interface is used by all API client constructors:

import { type ClientConfiguration } from "@sp-api-sdk/common";

Option	Type	Required	Description
auth	SellingPartnerApiAuth	Yes	Authentication instance from @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 retry configuration
logging	object	No	Request/response/error logging configuration
restrictedDataToken	string	No	Restricted Data Token for accessing PII
userAgent	string	No	Custom user-agent header

Regions

Three regions are supported, each with production and sandbox endpoints:

Region	Code	AWS Region	Production Endpoint
North America	na	us-east-1	https://sellingpartnerapi-na.amazon.com
Europe	eu	eu-west-1	https://sellingpartnerapi-eu.amazon.com
Far East	fe	us-west-2	https://sellingpartnerapi-fe.amazon.com

When sandbox is set to true, the sandbox variant of the endpoint is used (e.g. https://sandbox.sellingpartnerapi-eu.amazon.com).

Rate Limiting

When rateLimiting.retry is enabled, the SDK automatically retries HTTP 429 responses. The retry delay is calculated as follows:

• If the response includes an x-amzn-ratelimit-limit header, the delay is derived from it.
• Otherwise, the SDK falls back to the documented rate limits for the specific endpoint.
• If no rate limit information is available, a 60-second default delay is used.

You can optionally provide an onRetry callback to be notified on every retry:

rateLimiting: {
  retry: true,
  onRetry: ({delay, rateLimit, retryCount, error}) => {
    console.log(`Retry #${retryCount}, waiting ${delay}ms (rate limit: ${rateLimit})`)
  },
}

Logging

Logging is powered by axios-logger and can be configured independently for requests, responses, and errors:

logging: {
  request: true,   // or a RequestLogConfig object
  response: true,  // or a ResponseLogConfig object
  error: true,     // or an ErrorLogConfig object
}

Pass true to use sensible defaults (no headers logged for requests, headers logged for responses). Pass a configuration object to customize the behavior.

By default, request and response loggers use console.info, and the error logger uses console.error.

Warning: Enabling headers: true in the request logger will log authentication tokens. This should be disabled in production.

Error Handling

API errors are wrapped in SellingPartnerApiError, which extends AxiosError and adds context:

import { SellingPartnerApiError } from "@sp-api-sdk/common";

try {
  await client.searchOrders({ marketplaceIds: ["A1PA6795UKMFR9"] });
} catch (error) {
  if (error instanceof SellingPartnerApiError) {
    console.error(error.message); // e.g. "orders (2026-01-01) error: Response code 403"
    console.error(error.apiName); // e.g. "orders"
    console.error(error.apiVersion); // e.g. "2026-01-01"
    console.error(error.innerMessage); // Original axios error message
  }
}

License

MIT

Miscellaneous

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