eBay Docs

Changelog

Implementation status

RESTful API

Traditional API

Install

npm install ebay-api yarn add ebay-api

🚀 Usage & Quick start

NodeJS

importeBayApifrom'ebay-api';// or:// const eBayApi = require('ebay-api')consteBay=neweBayApi({appId:'-- also called Client ID --',certId:'-- also called Client Secret --',sandbox:false});constitem=awaiteBay.buy.browse.getItem('v1|254188828753|0');console.log(JSON.stringify(item,null,2));

Detailed configuration example

importeBayApifrom'ebay-api';consteBay=neweBayApi({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.htmlmarketplaceId:eBayApi.MarketplaceId.EBAY_US,// default. required for RESTful APIsacceptLanguage:eBayApi.Locale.en_US,// defaultcontentLanguage:eBayApi.Locale.en_US,// default.// optional parameters, should be omitted if not useddevId:'-- devId --',// required for traditional Trading APIruName:'-- eBay Redirect URL name --',// 'RuName' (eBay Redirect URL name) required for authorization code grantauthToken:'--  Auth\'n\'Auth for traditional API (used by trading) --',// can be set to use traditional API without code grant});

Browser

ESM

<scripttype="module">importeBayApifrom'https://cdn.jsdelivr.net/npm/ebay-api@latest/dist/ebay-api.min.mjs';// orimporteBayApiEsmfrom'https://esm.sh/ebay-api';</script>

UMD

<scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/ebay-api@latest/lib/ebay-api.min.js"></script><script>consteBay=neweBayApi({appId:'appId',certId:'certId',sandbox:false});// eBay.req.instance is AxiosInstance per defaulteBay.req.instance.interceptors.request.use((request)=>{// Add Proxyrequest.url='https://ebay.hendt.workers.dev/'+request.url;returnrequest;});eBay.buy.browse.getItem('v1|254188828753|0').then(item=>{console.log(JSON.stringify(item,null,2));}).catch(e=>{console.error(e);});</script>

🔧 eBayApi Config

Load config from environment

🐞 Debug

🔑 Access token types

User access token (authorization code grant flow)

Application access token (client credentials grant flow)

Auth'N'Auth

OAuth2: Exchanging the authorization code for a User access token

importeBayApifrom'ebay-api';// 1. Create new eBayApi instance and set the scope.consteBay=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 Accessconsturl=eBay.OAuth2.generateAuthUrl();console.log('Open URL',url);

Express example

importeBayApifrom'ebay-api';// This is your RUName endpoint like https://your-ebay.app/successapp.get('/success',asyncfunction(req,res){// 3. Get the parameter code that is placed as query parameter in redirected pageconstcode=req.query.code;// this is provided from eBayconsteBay=eBayApi.fromEnv();// or use new eBayApi()try{consttoken=awaiteBay.OAuth2.getToken(code);eBay.OAuth2.setCredentials(token);// store this token e.g. to a sessionreq.session.token=token// 5. Start using the APIconstorders=awaiteBay.sell.fulfillment.getOrders()res.send(orders);}catch(error){console.error(error)res.sendStatus(400)}});

importeBayApifrom'ebay-api';app.get('/orders/:id',asyncfunction(req,res){constid=req.params.id;consteBay=eBayApi.fromEnv();// or use new eBayApi(...)consttoken=req.session.token;if(!token){returnres.sendStatus(403);}eBay.OAuth2.setCredentials(token);// If token get's refreshedeBay.OAuth2.on('refreshAuthToken',(token)=>{req.session.token=token;});try{// 5. Start using the APIconstorder=awaiteBay.sell.fulfillment.getOrder(id);res.send(order);}catch(error){console.error(error)res.sendStatus(400)}});

Digital Signature

How to use Digital Signature

// 1. Create singning key and save it appropriatlyconstsigningKey=awaiteBay.developer.keyManagement.createSigningKey('ED25519');// 2. Set the signatureeBay.setSignature(signingKey)// or in constructoreBay=neweBayApi({appId:'...',certId:'...',signature:{jwe:signingKey.jwe,privateKey:signingKey.privateKey}});// 3. Use the 'sign' keyword in Restful APIconstsummary=awaiteBay.sell.finances.sign.getSellerFundsSummary();// 3. Or the 'sign' parameter in traditional APIconstaccount=awaiteBay.trading.GetAccount(null,{sign:true});

RESTful API

How to set the Scope

consteBay=neweBayApi({// ...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']);

Use apix.ebay.com or apiz.ebay.com (beta) endpoints

eBay.buy.browse.apix.getItem()// now it will use https://apix.ebay.comeBay.buy.browse.apiz.getItem()// now it will use https://apiz.ebay.com

eBay.buy.browse.api({subdomain:'apiy'}).getItem()// now it will use https://apiy.ebay.com

Return raw RESTful API response

eBay.buy.browse.api({returnResponse:true,// return the response instead of data}).getItem();

How to refresh the token

eBay.OAuth2.on('refreshAuthToken',(token)=>{console.log(token)// Store this token in DB});// for client tokeneBay.OAuth2.on('refreshClientToken',(token)=>{console.log(token)// Store this token in DB});

consttoken=awaiteBay.OAuth2.refreshToken();// will refresh Auth Token if set, otherwise the client token if set.

Additional request headers

RESTful API headers

consteBay=neweBayApi();eBay.buy.browse.api({headers:{'X-EBAY-SOA-GLOBAL-ID':'EBAY-DE'}}).getItem('v1|382282567190|651094235351').then((item)=>{console.log(item)})

Traditional API headers

eBay.trading.AddFixedPriceItem({Item:{Title:'title',Description:{__cdata:'<div>test</div>'}}},{headers:{'X-EBAY-SOA-GLOBAL-ID':'EBAY-DE'}})

Low level: use the Axios interceptor to manipulate the request

importeBayApifrom'ebay-api';consteBay=neweBayApi(/* {  your config here } */);eBay.req.instance.interceptors.request.use((request)=>{// Add Headerrequest.headers['X-EBAY-SOA-GLOBAL-ID']='EBAY-DE';returnrequest;})

Handle JSON GZIP response e.g fetchItemAspects

npm install zlib# or yarn add zlib

importeBayApifrom'ebay-api';importzlibfrom'zlib';consttoString=(data)=>newPromise((resolve)=>{zlib.gunzip(data,(err,output)=>{if(err)throwerr;resolve(output.toString());});});consteBay=neweBayApi(/* {  your config here } */);try{constdata=awaiteBay.commerce.taxonomy.fetchItemAspects(/* categoryTreeId */);constresult=awaittoString(data);console.log(result)}catch(error){console.error(error);}

Handling errors

importeBayApifrom'ebay-api';import{EBayApiError}from'ebay-api/lib/errors';consteBay=neweBayApi(/* {  your config here } */);try{constresult=awaiteBay.trading.GetItem({ItemID:'itemId',});console.log(result);}catch(error){if(errorinstanceofEBayApiError&&error.errorCode===17){// Item not found}else{throwerror;}// in error there is also the field "meta" with the responseif(errorinstanceofEBayApiError&&error.meta?.res?.status===404){// not found// The first errorconsole.log(error?.firstError);}}

Controlling Traditional XML request and response

exporttypeOptions={raw?:boolean// return raw XMLparseOptions?:X2jOptions// https://github.com/NaturalIntelligence/fast-xml-parserxmlBuilderOptions?:XmlBuilderOptions// https://github.com/NaturalIntelligence/fast-xml-parseruseIaf?:boolean// use IAF in header instead of Bearerheaders?:Headers// additional Headers (key, value)hook?:(xml)=>BodyHeaders// hook into the request to modify the body and headers};

Parse JSON Array

eBay.trading.SetNotificationPreferences({UserDeliveryPreferenceArray:[{NotificationEnable:{EventType:'ItemListed',EventEnable:'Enable',}},{NotificationEnable:{EventType:'ItemSold',EventEnable:'Enable',},}],},{xmlBuilderOptions:{oneListGroup:true}})

<UserDeliveryPreferenceArray>  <NotificationEnable>    <EventType>ItemListed</EventType>    <EventEnable>Enable</EventEnable>  </NotificationEnable>  <NotificationEnable>    <EventType>ItemSold</EventType>    <EventEnable>Enable</EventEnable>  </NotificationEnable></UserDeliveryPreferenceArray>

Examples

Trading - AddFixedPriceItem (CDATA)

eBay.trading.AddFixedPriceItem({Item:{Title:'title',Description:{__cdata:'<div>test</div>'}}})

Trading - ReviseFixedPriceItem (Update the price of an item)

eBay.trading.ReviseFixedPriceItem({Item:{ItemID:'itemId',StartPrice:'startPrice'}})

Buy - getItem

eBay.buy.browse.getItem('v1|382282567190|651094235351').then(a=>{console.log(a);}).catch(e=>{console.log(e)});

Post-Order - getReturn

eBay.postOrder.return.getReturn('5132021997').then(a=>{console.log(a);}).catch(e=>{console.log(e)});

Finding - findItemsByProduct (use XML attributes and value)

eBay.finding.findItemsByProduct({productId:{'@_type':'ReferenceID','#value':'53039031'}})// will produce:// <productId type="ReferenceID">53039031</productId>

Finding - findItemsIneBayStores

eBay.finding.findItemsIneBayStores({storeName:'HENDT'},{raw:true}).then(result=>{// Return raw XMLconsole.log(result);});

Finding - findItemsAdvanced (findItemsByKeywords)

eBay.finding.findItemsAdvanced({itemFilter:[{name:'Seller',value:'hendt_de'}],keywords:'katze'}).then(result=>{console.log(result);});

Trading - GetMyeBaySelling

eBay.trading.GetMyeBaySelling({SoldList:{Include:true,Pagination:{EntriesPerPage:20,PageNumber:1}}}).then(data=>{console.log(data.results)});

FAQ

Contribution

Supported By

📝 License