This eBay API implements both Traditional (xml) and the RESTful eBay API.
It supports client credentials grant and authorization code grant (Auth'N'Auth, OAuth2 and IAF). Digital Signature is supported too.
v8.7.0 is the latest release.| API | Implemented |
|---|---|
| Buy API | ✔ Browse API v1.10.0✔ Deal API v1.3.0✔ Feed API v1.3.1✔ Marketing API v1_beta.1.0✔ Offer API v1_beta.0.0✔ Order API v1_beta.20.0✔ Marketplace Insights API v1_beta.2.2 |
| Commerce API | ✔ Catalog API v1_beta.3.1✔ Charity API v1.2.0✔ Identity API v1.0.0✔ Notification API v1.2.0✔ Taxonomy API v1.0.0✔ Translation API v1_beta.1.4✔ Media API v1_beta.1.0 |
| Developer API | ✔ Analytics API |
| Post Order API | ✔ Cancellation API ✔ Case Management API ✔ Inquiry API ✔ Return API |
| Sell API | ✔ Account API v1.9.0✔ Analytics API v1.3.0✔ Compliance API v1.4.1✔ Feed API v1.3.1✔ Finance API v1.9.0✔ Fulfillment API v1.19.10✔ Inventory API v1.14.0✔ Listing API v1_beta.2.1✔ Logistics API v1_beta.0.0✔ Marketing API v1.17.0✔ Metadata API v1.4.2✔ Negotiation API v1.1.0✔ Recommendation API v1.1.0 |
| API | Implemented |
|---|---|
| Finding API | ✔ |
| Shopping API | ✔ |
| Merchandising API | ✔ |
| Trading API | ✔ |
| Client Alerts API | ✔ |
| Feedback API | ✔ |
npm install ebay-api
yarn add ebay-api
Sign up for an API key here: Developer Account. Checkout API examples.
import eBayApi from 'ebay-api';
// or:
// const eBayApi = require('ebay-api')
const eBay = new eBayApi({
appId: '-- also called Client ID --',
certId: '-- also called Client Secret --',
sandbox: false
});
const item = await eBay.buy.browse.getItem('v1|254188828753|0');
console.log(JSON.stringify(item, null, 2));
import eBayApi from 'ebay-api';
const eBay = new eBayApi({
appId: '-- also called Client ID --',
certId: '-- also called Client Secret --',
sandbox: false,
siteId: eBayApi.SiteId.EBAY_US, // required for traditional APIs, see https://developer.ebay.com/DevZone/merchandising/docs/Concepts/SiteIDToGlobalID.html
marketplaceId: eBayApi.MarketplaceId.EBAY_US, // default. required for RESTful APIs
acceptLanguage: eBayApi.Locale.en_US, // default
contentLanguage: eBayApi.Locale.en_US, // default.
// optional parameters, should be omitted if not used
devId: '-- devId --', // required for traditional Trading API
ruName: '-- eBay Redirect URL name --', // 'RuName' (eBay Redirect URL name) required for authorization code grant
authToken: '-- Auth\'n\'Auth for traditional API (used by trading) --', // can be set to use traditional API without code grant
});
Check out live example: https://hendt.github.io/ebay-api/. Because of the eBay CORS problems a Proxy server is required to use the API in the Browser.
For testing purpose you can use https://ebay.hendt.workers.dev/ url as proxy. You can also set up your own Proxy
server. We have added a example for cloudfront
workers: https://github.com/hendt/ebay-api/blob/master/proxy/worker.js
Or use [https://github.com/Rob--W/cors-anywhere](CORS Anywhere is a NodeJS proxy) (works very well with heroku.com).
<script type="module">
import eBayApi from 'https://cdn.jsdelivr.net/npm/ebay-api@latest/dist/ebay-api.min.mjs';
// or
import eBayApiEsm from 'https://esm.sh/ebay-api';
</script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/ebay-api@latest/lib/ebay-api.min.js"></script>
<script>
const eBay = new eBayApi({
appId: 'appId',
certId: 'certId',
sandbox: false
});
// eBay.req.instance is AxiosInstance per default
eBay.req.instance.interceptors.request.use((request) => {
// Add Proxy
request.url = 'https://ebay.hendt.workers.dev/' + request.url;
return request;
});
eBay.buy.browse.getItem('v1|254188828753|0').then(item => {
console.log(JSON.stringify(item, null, 2));
}).catch(e => {
console.error(e);
});
</script>
The first (required) parameter in eBayApi instance takes an object with following properties:
| Name | Occurrence | Description |
|---|---|---|
| appId | Required | App ID (Client ID) from Application Keys. |
| certId | Required | Cert ID (Client Secret) from Application Keys. |
| devId | Conditionally | The Dev Id from Application Keys. |
| sandbox | RequiredDefault: | If true, the Sandbox Environment will be used. |
| ruName | Conditionally | The redirect_url value. More info. |
| autoRefreshToken | RequiredDefault: | Auto refresh the token if it's expired. |
| siteId Traditional | RequiredDefault: | eBay site to which you want to send the request (Trading API, Shopping API). |
| authToken Traditional | Optional | The Auth'N'Auth token. The traditional authentication and authorization technology used by the eBay APIs. |
| marketplaceId RESTful | RequiredDefault: | Docs REST HTTP Header. X-EBAY-C-MARKETPLACE-ID identifies the user's business context and is specified using a marketplace ID value. Note that this header does not indicate a language preference or consumer location. |
| scope RESTful | ConditionallyDefault: | The scopes assigned to your application allow access to different API resources and functionality. |
| endUserCtx RESTful | Conditionally recommended RESTful | Docs X-EBAY_C_ENDUSERCTX provides various types of information associated with the request. |
| contentLanguage RESTful | Conditionally requiredDefault: | DocsContent-Language indicates the locale preferred by the client for the response. |
| acceptLanguage RESTful | OptionalDefault: | Docs Accept-Language indicates the natural language the client prefers for the response. This specifies the language the client wants to use when the field values provided in the request body are displayed to consumers. |
Use eBayApi.fromEnv() to load data from environment variables.
| Name | Value |
|---|---|
| appId | process.env.EBAY_APP_ID |
| certId | process.env.EBAY_CERT_ID |
| devId | process.env.EBAY_DEV_ID |
| authToken | process.env.EBAY_AUTH_TOKEN |
| siteId | process.env.EBAY_SITE_ID |
| marketplaceId | process.env.EBAY_MARKETPLACE_ID |
| ruName | process.env.EBAY_RU_NAME |
| sandbox | process.env.EBAY_SANDBOX === 'true' |
To see node debug logs use DEBUG=ebay:* environment variable.
See the full Documentation here.
Client credentials grant flow mints a new Application access token. Authorization code grant flow mints a new User access token.
👉 Recommended for all API Calls.
You must employ a User token to call any interface that accesses or modifies data that is owned by the user (such as user information and account data). To get a User token, the users of your app must grant your application the permissions it needs to act upon their behalf. This process is called user consent. With the user consent flow, each User token contains the set of scopes for which the user has granted their permission (eBay Token Types).
👉 Recommended for API calls that will only request application data (GET method, and it's also restricted).
Application tokens are general-use tokens that give access to interfaces that return application data. For example, many GET requests require only an Application token for authorization. (eBay Token Types)
If no other token is set, this token will be obtained automatically in the process of calling an RESTful API.
👉 The "old" way. Only works with Traditional API. Checkout the Auth'N'Auth example.
You can also generate the token on eBay developer page and use it directly (see Detailed configuration example).
import eBayApi from 'ebay-api';
// 1. Create new eBayApi instance and set the scope.
const eBay = eBayApi.fromEnv();
eBay.OAuth2.setScope([
'https://api.ebay.com/oauth/api_scope',
'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
'https://api.ebay.com/oauth/api_scope/sell.fulfillment'
]);
// 2. Generate and open Url and Grant Access
const url = eBay.OAuth2.generateAuthUrl();
console.log('Open URL', url);
After you granted success, eBay will redirect you to your 'Auth accepted URL' and add a query parameter code
This is how it would look like if you use express:
import eBayApi from 'ebay-api';
// This is your RUName endpoint like https://your-ebay.app/success
app.get('/success', async function (req, res) {
// 3. Get the parameter code that is placed as query parameter in redirected page
const code = req.query.code; // this is provided from eBay
const eBay = eBayApi.fromEnv(); // or use new eBayApi()
try {
const token = await eBay.OAuth2.getToken(code);
eBay.OAuth2.setCredentials(token);
// store this token e.g. to a session
req.session.token = token
// 5. Start using the API
const orders = await eBay.sell.fulfillment.getOrders()
res.send(orders);
} catch (e) {
console.error(e)
res.sendStatus(400)
}
});
If token is already in session:
import eBayApi from 'ebay-api';
app.get('/orders/:id', async function (req, res) {
const id = req.params.id;
const eBay = eBayApi.fromEnv(); // or use new eBayApi(...)
const token = req.session.token;
if (!token) {
return res.sendStatus(403);
}
eBay.OAuth2.setCredentials(token);
// If token get's refreshed
eBay.OAuth2.on('refreshAuthToken', (token) => {
req.session.token = token;
});
try {
// 5. Start using the API
const order = await eBay.sell.fulfillment.getOrder(id);
res.send(order);
} catch (e) {
console.error(e)
res.sendStatus(400)
}
});
Signatures are required when the call is made for EU- or UK-domiciled sellers, and only for the following APIs/methods:
eBay.finances.XXX.sign.YYY())eBay.sell.fulfillment.sign.issueRefund())eBay.trading.GetAccount(null, { sign: true })))eBay.postOrder.inquiry.sign.issueInquiryRefund())eBay.postOrder.inquiry.sign.issueCaseRefund())eBay.postOrder.inquiry.sign.issueReturnRefund())eBay.postOrder.inquiry.sign.processReturnRequest())eBay.postOrder.inquiry.sign.createCancellation())eBay.postOrder.inquiry.sign.approveCancellationRequest())// 1. Create singning key and save it appropriatly
const signingKey = await eBay.developer.keyManagement.createSigningKey('ED25519');
// 2. Set the signature
eBay.setSignature(signingKey)
// or in constructor
eBay = new eBayApi({
appId: '...',
certId: '...',
signature: {
jwe: signingKey.jwe,
privateKey: signingKey.privateKey
}
});
// 3. Use the 'sign' keyword in Restful API
const summary = await eBay.sell.finances.sign.getSellerFundsSummary();
// 3. Or the 'sign' parameter in traditional API
const account = await eBay.trading.GetAccount(null, {sign: true});
const eBay = new eBayApi({
// ...
scope: ['https://api.ebay.com/oauth/api_scope']
});
// Or:
eBay.OAuth2.setScope([
'https://api.ebay.com/oauth/api_scope',
'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
'https://api.ebay.com/oauth/api_scope/sell.fulfillment'
]);
For some APIs, eBay use a apix/apiz subdomain. To use these subdomains you can use .apix/.apiz before the api
call like this:
eBay.buy.browse.apix.getItem() // now it will use https://apix.ebay.com
eBay.buy.browse.apiz.getItem() // now it will use https://apiz.ebay.com
In any case eBay adds a new subdomain, it's also possible to configure whatever you want:
eBay.buy.browse.api({subdomain: 'apiy'}).getItem() // now it will use https://apiy.ebay.com
eBay.buy.browse.api({
returnResponse: true, // return the response instead of data
}).getItem();
If autoRefreshToken is set to true (default value) the token will be automatically refreshed when eBay response
with invalid access token error.
Use Event Emitter to get the token when it gets successfully refreshed.
eBay.OAuth2.on('refreshAuthToken', (token) => {
console.log(token)
// Store this token in DB
});
// for client token
eBay.OAuth2.on('refreshClientToken', (token) => {
console.log(token)
// Store this token in DB
});
To manual refresh the auth token use eBay.OAuth2.refreshAuthToken() and for the client
token use eBay.OAuth2.refreshClientToken().
Keep in mind that you need the 'refresh_token' value set.
const token = await eBay.OAuth2.refreshToken();
// will refresh Auth Token if set, otherwise the client token if set.
Sometimes you want to add additional headers to the request like a GLOBAL-ID X-EBAY-SOA-GLOBAL-ID.
You have multiple options to do this.
const eBay = new eBayApi();
eBay.buy.browse.api({
headers: {
'X-EBAY-SOA-GLOBAL-ID': 'EBAY-DE'
}
}).getItem('v1|382282567190|651094235351').then((item) => {
console.log(item)
})
You can pass headers directly in the method call in the second parameter:
eBay.trading.AddFixedPriceItem({
Item: {
Title: 'title',
Description: {
__cdata: '<div>test</div>'
}
}
}, {
headers: {
'X-EBAY-SOA-GLOBAL-ID': 'EBAY-DE'
}
})
import eBayApi from 'ebay-api';
const eBay = new eBayApi(/* { your config here } */);
eBay.req.instance.interceptors.request.use((request) => {
// Add Header
request.headers['X-EBAY-SOA-GLOBAL-ID'] = 'EBAY-DE';
return request;
})
You need a decompress library installed like zlib.
npm install zlib # or yarn add zlib
import eBayApi from 'ebay-api';
import zlib from 'zlib';
const toString = (data) => new Promise((resolve) => {
zlib.gunzip(data, (err, output) => {
if (err) throw err;
resolve(output.toString());
});
});
const eBay = new eBayApi(/* { your config here } */);
try {
const data = await eBay.commerce.taxonomy.fetchItemAspects(/* categoryTreeId */);
const result = await toString(data);
console.log(result)
} catch (e) {
console.error(e);
}
The second parameter in the traditional API has the following options:
export type Options = {
raw?: boolean // return raw XML
parseOptions?: object // https://github.com/NaturalIntelligence/fast-xml-parser
useIaf?: boolean // use IAF in header instead of Bearer
headers?: Headers // additional Headers (key, value)
hook?: (xml) => BodyHeaders // hook into the request to modify the body and headers
};
Fast XML is used to parse the XML. You can pass the parse
option to parseOptions parameter.
You can submit your description using CDATA if you want to use HTML or XML.
eBay.trading.AddFixedPriceItem({
Item: {
Title: 'title',
Description: {
__cdata: '<div>test</div>'
}
}
})
eBay.trading.ReviseFixedPriceItem({
Item: {
ItemID: 'itemId',
StartPrice: 'startPrice'
}
})
eBay.buy.browse.getItem('v1|382282567190|651094235351').then(a => {
console.log(a);
}).catch(e => {
console.log(e)
});
eBay.postOrder.return.getReturn('5132021997').then(a => {
console.log(a);
}).catch(e => {
console.log(e)
});
eBay.finding.findItemsByProduct({
productId: {
'@_type': 'ReferenceID',
'#value': '53039031'
}
})
// will produce:
// <productId type="ReferenceID">53039031</productId>
eBay.finding.findItemsIneBayStores({
storeName: 'HENDT'
}, {raw: true}).then(result => {
// Return raw XML
console.log(result);
});
eBay.finding.findItemsAdvanced({
itemFilter: [{
name: 'Seller',
value: 'hendt_de'
}],
keywords: 'katze'
}).then(result => {
console.log(result);
});
eBay.trading.GetMyeBaySelling({
SoldList: {
Include: true,
Pagination: {
EntriesPerPage: 20,
PageNumber: 1
}
}
}).then(data => {
console.log(data.results)
});
No. This library has already all authentication implemented and support also auto refreshing token.
IAF stands for IDENTITY ASSERTION FRAMEWORK. The traditional API supports IAF. That means you can use the OAuth2 token with the traditional APIs.
Yes. Checkout the Browser example and Node Example here.
endUserCtx.Check here
MIT.
FAQs
eBay API for Node and Browser
The npm package ebay-api receives a total of 3,281 weekly downloads. As such, ebay-api popularity was classified as popular.
We found that ebay-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.