{"id":13097,"library":"ebay-api","title":"eBay API Client","description":"The `ebay-api` package provides a comprehensive client library for interacting with both the Traditional (XML) and modern RESTful eBay APIs, supporting Node.js and browser environments. Currently at version 9.5.1, it offers robust functionality for accessing various eBay services, including Buy, Commerce, and others, with an active release cadence reflecting ongoing development and API updates. Key differentiators include built-in support for multiple authentication flows like client credentials grant, authorization code grant (OAuth2, Auth'N'Auth), and Digital Signatures, simplifying complex eBay authentication processes. It also ships with TypeScript types, enhancing developer experience and type safety for large-scale applications.","status":"active","version":"9.5.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/hendt/ebay-api","tags":["javascript","api","eBay","Shopping","Searching","products","Browse","Category","FindingApi","typescript"],"install":[{"cmd":"npm install ebay-api","lang":"bash","label":"npm"},{"cmd":"yarn add ebay-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add ebay-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`eBayApi` is the default export of the module. Attempting to import it as a named export will result in an undefined value or a runtime error.","wrong":"import { eBayApi } from 'ebay-api';","symbol":"eBayApi","correct":"import eBayApi from 'ebay-api';"},{"note":"When importing only types in TypeScript, always use `import type` to ensure no runtime code is generated, preventing potential import errors or unnecessary bundle sizes.","wrong":"import { Config } from 'ebay-api';","symbol":"Config","correct":"import type { Config } from 'ebay-api';"},{"note":"`fromEnv` is a static method of the `eBayApi` class, designed to load configuration from environment variables. It should be called directly on the imported default `eBayApi` class, not imported as a standalone named export.","wrong":"import { fromEnv } from 'ebay-api';","symbol":"eBayApi.fromEnv","correct":"import eBayApi from 'ebay-api'; const eBay = eBayApi.fromEnv();"}],"quickstart":{"code":"import eBayApi from 'ebay-api';\nimport 'dotenv/config'; // Optional: for loading .env variables\n\n// Ensure your eBay Developer credentials are set as environment variables (e.g., EBAY_APP_ID, EBAY_CERT_ID)\n// You can obtain these from your eBay Developer Program account: https://developer.ebay.com/signin?tab=register\n\nconst EBAY_APP_ID = process.env.EBAY_APP_ID ?? '-- also called Client ID --';\nconst EBAY_CERT_ID = process.env.EBAY_CERT_ID ?? '-- also called Client Secret --';\nconst EBAY_RUN_IN_SANDBOX = process.env.EBAY_RUN_IN_SANDBOX === 'true'; // Set to 'true' in .env for sandbox\n\nif (EBAY_APP_ID === '-- also called Client ID --' || EBAY_CERT_ID === '-- also called Client Secret --') {\n  console.error('Error: Please configure your eBay API credentials. Check your .env file or direct configuration.');\n  process.exit(1);\n}\n\nconst eBay = new eBayApi({\n  appId: EBAY_APP_ID,\n  certId: EBAY_CERT_ID,\n  sandbox: EBAY_RUN_IN_SANDBOX, // Set to true for sandbox environment; false for production\n  // siteId: 0 // Example: Specify site ID for certain traditional APIs (e.g., 0 for US)\n});\n\nasync function getExampleItem() {\n  try {\n    // Example: Fetch details for a specific item using the Buy Browse API\n    const itemId = 'v1|254188828753|0'; // A publicly accessible sample item ID\n    console.log(`Fetching item details for ID: ${itemId}...`);\n    const item = await eBay.buy.browse.getItem(itemId);\n    console.log('Successfully fetched item details:');\n    console.log(JSON.stringify(item, null, 2));\n\n    // Uncomment for a search example:\n    // console.log('\\nPerforming a search for \"laptop\"...');\n    // const searchResults = await eBay.buy.browse.search({ q: 'laptop', limit: 3 });\n    // console.log('Search Results:');\n    // console.log(JSON.stringify(searchResults.itemSummaries, null, 2));\n\n  } catch (error: any) {\n    console.error('An error occurred during the API call:', error.message || error);\n    if (error.response) {\n      console.error('Detailed API Error Response:', error.response.data);\n    }\n  }\n}\n\ngetExampleItem();","lang":"typescript","description":"This quickstart demonstrates how to initialize the eBay API client using environment variables for credentials and fetch details for a specific item using the Buy Browse API, including error handling."},"warnings":[{"fix":"If your application relied on API calls directly returning the data, ensure `returnResponse` is either `false` in your configuration or adjust your code to access `response.data`.","message":"In `v7.0.0`, the API configuration introduced `returnResponse`. If set to `true`, API calls will return the full HTTP response object instead of directly returning the data payload.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Always verify that your `appId`, `certId`, and `sandbox` setting correctly match the environment (production or sandbox) and credentials you obtained from the eBay Developer Program.","message":"Incorrect configuration of `appId` (Client ID), `certId` (Client Secret), or `sandbox` mode is a common source of authentication and authorization errors. Using production keys in the sandbox environment or vice-versa will lead to unexpected behavior or failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the official eBay API documentation and the `ebay-api` library's guides for the correct authentication method required for the specific API endpoint you are targeting. Ensure refresh tokens are managed properly for long-lived access.","message":"eBay's API ecosystem utilizes several distinct authentication flows (Client Credentials, Authorization Code Grant/OAuth2, Auth'N'Auth, Digital Signature). Choosing the wrong flow for a specific API operation or incorrectly implementing the chosen flow can lead to persistent authorization errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `appId` and `certId` are correctly configured in `eBayApi` constructor or environment variables. Verify your access token is valid and refreshed if using OAuth2/Auth'N'Auth.","cause":"Missing or invalid API credentials (`appId`, `certId`) or an expired/incorrect access token.","error":"\"Unauthorized\" or \"Authentication required\""},{"fix":"Consult the eBay API documentation and the `ebay-api` library examples for the specific API call. Double-check required parameters and their format.","cause":"An incorrect endpoint, missing required parameters for an API call, or a malformed request body.","error":"\"Invalid API call, API error, or missing required parameter\""},{"fix":"Change `sandbox: false` in your `eBayApi` configuration and use production credentials if the API is production-only. Alternatively, check if a sandbox equivalent exists for your desired API or if you are using an outdated API version.","cause":"Attempting to call an eBay API that is only available in the production environment while `sandbox` is set to `true`, or the API version is not supported in the current environment.","error":"\"This API is not supported in the sandbox environment\" or \"The resource you requested cannot be found.\""}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}