@hendt/ebay-api

ATTENTION:

Description

• API Browser Examples
• API Documentation

eBay Docs

• eBay API Explorer
• eBay API Docs

Changelog

• v6.0.0 is the latest release.
• See here for the full changelog.

Implementation status

RESTful API

Traditional API

Install

npm install ebay-api 
yarn add ebay-api

🚀 Usage & Quick start

NodeJS

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));

Detailed configuration example

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, // defautl. required for RESTful APIs
  acceptLanguage: eBayApi.Locale.en_US, // defautl
  contentLanguage: eBayApi.ContentLanguage.en_US, // defautl.

  // 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
});

Browser

<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>

🔧 eBayApi Config

Default: false

Default: true

Default: SiteId.EBAY_US

Default: MarketplaceId.EBAY_US

Default:
['https://api.ebay.com/oauth/api_scope'] 

Default: ContentLanguage.en_US

Default: Locale.en_US

Load config from environment

User access token (authorization code grant flow)

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).

Application access token (client credentials grant flow)

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.

Auth'N'Auth

OAuth2: Exchanging the authorization code for a User access token

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);

Express example

import eBayApi from 'ebay-api';

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)
  }
});

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)
  }
});

RESTful API

How to set the Scope

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'
]);

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

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

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

How to refresh the token

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
});

const token = await eBay.OAuth2.refreshToken();
// will refresh Auth Token if set, otherwise the client token if set.

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)
})

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;
})

```javascript
  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);
  }

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
};

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 XML
    console.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

1. Do I need the eBay OAuth Client dependency?

1. What does IAF mean?

1. Is it possible to Upload Pictures directly to EPS?

Contribution

Supported By

📝 License