eBay TypeScript/JavaScript API for Browser and Node
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.
eBay Docs
Changelog
v8.7.2-RC.0
is the latest release.See here for the full changelog.
Implementation status
RESTful API
API | Implemented |
---|---|
Buy API | ✔ Browse API |
Commerce API | ✔ Catalog API |
Developer API | ✔ Analytics API |
Post Order API | ✔ Cancellation API ✔ Case Management API ✔ Inquiry API ✔ Return API |
Sell API | ✔ Account API |
Traditional API
API | Implemented |
---|---|
Finding API | ✔ |
Shopping API | ✔ |
Merchandising API | ✔ |
Trading API | ✔ |
Client Alerts API | ✔ |
Feedback API | ✔ |
Install
🚀 Usage & Quick start
Sign up for an API key here: Developer Account. Checkout API examples.
NodeJS
Detailed configuration example
Browser
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).
ESM
UMD
🔧 eBayApi Config
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 | Required | If true, the Sandbox Environment will be used. |
ruName | Conditionally | The redirect_url value. More info. |
autoRefreshToken | Required | Auto refresh the token if it's expired. |
siteId Traditional | Required | 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 | Required | 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 | Conditionally | 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 required | DocsContent-Language indicates the locale preferred by the client for the response. |
acceptLanguage RESTful | Optional | 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. |
Load config from environment
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' |
🐞 Debug
To see node debug logs use DEBUG=ebay:*
environment variable.
🔑 Access token types
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.
User access token (authorization code grant flow)
👉 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).
Application access token (client credentials grant flow)
👉 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.
Auth'N'Auth
👉 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).
OAuth2: Exchanging the authorization code for a User access token
After you granted success, eBay will redirect you to your 'Auth accepted URL' and add a query parameter code
Express example
This is how it would look like if you use express
:
If token is already in session:
Digital Signature
Signatures are required when the call is made for EU- or UK-domiciled sellers, and only for the following APIs/methods:
All methods in the Finances API -> (
eBay.finances.XXX.sign.YYY()
)issueRefund in the Fulfillment API -> (
eBay.sell.fulfillment.sign.issueRefund()
)GetAccount in the Trading API -> (
eBay.trading.GetAccount(null, { sign: true }))
)The following methods in the Post-Order API:
Issue Inquiry Refund -> (
eBay.postOrder.inquiry.sign.issueInquiryRefund()
)Issue case refund -> (
eBay.postOrder.inquiry.sign.issueCaseRefund()
)Issue return refund -> (
eBay.postOrder.inquiry.sign.issueReturnRefund()
)Process Return Request -> (
eBay.postOrder.inquiry.sign.processReturnRequest()
)Create Cancellation Request -> (
eBay.postOrder.inquiry.sign.createCancellation()
)Approve Cancellation Request -> (
eBay.postOrder.inquiry.sign.approveCancellationRequest()
)
How to use Digital Signature
RESTful API
How to set the Scope
Use apix.ebay.com or apiz.ebay.com (beta) endpoints
For some APIs, eBay use a apix
/apiz
subdomain. To use these subdomains you can use .apix
/.apiz
before the api call like this:
In any case eBay adds a new subdomain, it's also possible to configure whatever you want:
Return raw RESTful API response
How to refresh the token
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.
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.
Additional request headers
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.
RESTful API headers
Traditional API headers
You can pass headers directly in the method call in the second parameter:
Low level: use the Axios interceptor to manipulate the request
Handle JSON GZIP response e.g fetchItemAspects
You need a decompress library installed like zlib
.
Controlling Traditional XML request and response
The second parameter in the traditional API has the following options:
Fast XML is used to parse the XML. You can pass the parse option to parseOptions
parameter.
Examples
Trading - AddFixedPriceItem (CDATA)
You can submit your description using CDATA if you want to use HTML or XML.
Trading - ReviseFixedPriceItem (Update the price of an item)
Buy - getItem
Post-Order - getReturn
Finding - findItemsByProduct (use XML attributes and value)
Finding - findItemsIneBayStores
Finding - findItemsAdvanced (findItemsByKeywords)
Trading - GetMyeBaySelling
FAQ
Do I need the eBay OAuth Client dependency?
No. This library has already all authentication implemented and support also auto refreshing token.
What does IAF mean?
IAF stands for IDENTITY ASSERTION FRAMEWORK. The traditional API supports IAF. That means you can use the OAuth2 token with the traditional APIs.
Is it possible to Upload Pictures directly to EPS?
Yes. Checkout the Browser example and Node Example here.
itemAffiliateWebUrl is missing in eBay.buy.browse.search call You have to set
endUserCtx
.
Contribution
Check here
Supported By
📝 License
MIT.
Last updated