v2.0.0 — Now with 13 API modules

The complete eBay API wrapper for Node.js

Fully-typed TypeScript SDK covering Browse, Inventory, Fulfillment, Marketing, and more. Zero dependencies.

Get Started Star on GitHub
$ npm install @tradebuddyhq/ebay-wrapper
13
API Modules
100+
Endpoints
0
Dependencies
1200+
TypeScript Types
Features

Everything you need to build on eBay

A production-ready SDK with built-in auth, rate limiting, retries, and pagination — so you can focus on your app.

🔑

OAuth 2.0 Built-In

Client Credentials for app tokens and Authorization Code Grant for user tokens. Automatic caching and refresh-ahead.

🛡️

Rate Limiting

Configurable token-bucket rate limiter prevents you from hitting eBay's API limits. Set your own requests-per-second cap.

🔄

Automatic Retries

Exponential backoff with jitter on 429 and 5xx errors. Configurable max retry attempts to keep your app resilient.

📄

Auto-Pagination

Async iterators and collect-all helpers make it easy to page through large result sets without manual offset management.

🎯

Full TypeScript Types

1,200+ lines of request/response types. Get autocomplete and compile-time checks for every endpoint parameter.

Zero Dependencies

Uses native fetch (Node.js 18+). No bloated dependency tree — just your code and the eBay API.

API Coverage

13 modules. One client.

Access every major eBay REST API through a single, consistent interface.

Buy

Browse

6 endpoints

Buy

Order

7 endpoints

Buy

Marketplace Insights

1 endpoint

Sell

Inventory

18 endpoints

Sell

Fulfillment

6 endpoints

Sell

Account

20 endpoints

Sell

Marketing

17 endpoints

Sell

Finances

8 endpoints

Commerce

Taxonomy

7 endpoints

Commerce

Catalog

2 endpoints

Dev

Analytics

Rate limits

Quick Start

Up and running in minutes

Get your API credentials from the eBay Developer Program, install the package, and start making requests.

  • Search, browse, and buy items
  • Manage inventory and listings
  • Process orders and fulfillment
  • Run Promoted Listings campaigns
  • Track finances and payouts
  • Explore categories and catalog
app.ts
import { Client } from "@tradebuddyhq/ebay-wrapper";

const client = new Client({
  clientId:     process.env.EBAY_CLIENT_ID!,
  clientSecret: process.env.EBAY_CLIENT_SECRET!,
  marketplaceId: "EBAY_US",
});

// Search for items
const results = await client.buy.browse.search({
  q: "mechanical keyboard",
  limit: 5,
});

for (const item of results.itemSummaries ?? []) {
  console.log(
    `${item.title} — ${item.price?.value}`
  );
}
OAuth

User tokens for Sell APIs

Access Inventory, Fulfillment, Account, Marketing, and Finances with the built-in Authorization Code Grant flow.

  • Generate authorization URL
  • Exchange code for tokens
  • Auto-refresh expired tokens
oauth.ts
// 1. Send the user to eBay to authorize
const authUrl = client.oauth.generateAuthUrl(
  "https://yourapp.com/callback"
);

// 2. Exchange the callback code
const tokens = await client.oauth.exchangeCodeForToken(
  code, "https://yourapp.com/callback"
);

// 3. Use the refresh token going forward
const seller = new Client({
  clientId, clientSecret,
  refreshToken: tokens.refresh_token,
});

const orders = await seller.sell
  .fulfillment.getOrders();
Pagination

Auto-paginate everything

Iterate through pages with async iterators or collect all results at once. No manual offset tracking needed.

pagination.ts
import { paginate, paginateAll } from
  "@tradebuddyhq/ebay-wrapper";

// Iterate page by page
for await (const page of paginate(
  (p) => client.buy.browse.search(p),
  { q: "laptop", limit: 50 }
)) {
  console.log(page.total);
}

// Or collect everything
const all = await paginateAll(
  (p) => client.buy.browse.search(p),
  { q: "laptop", limit: 200 },
  (page) => page.itemSummaries
);
Error Handling

Typed error hierarchy

Catch specific error types for rate limits, auth failures, timeouts, and API errors. Each carries structured data from eBay's response.

errors.ts
import {
  EbayError,
  EbayRateLimitError,
  EbayAuthError,
  EbayTimeoutError
} from "@tradebuddyhq/ebay-wrapper";

try {
  await client.buy.browse.getItem(id);
} catch (err) {
  if (err instanceof EbayRateLimitError)
    console.log(err.retryAfterMs);
  else if (err instanceof EbayAuthError)
    console.log("Auth failed");
  else if (err instanceof EbayError)
    console.log(err.status, err.errors);
}

Start building with eBay APIs today

Install the package and make your first API call in under a minute.

View on npm Documentation