Ebay client functions for authorisation and accessing ebay apis

Usage no npm install needed!

<script type="module">
  import chanochEbayApiClient from 'https://cdn.skypack.dev/@chanoch/ebay-api-client';


  1. Exchange the ebay user authorisation code for an user access token set.from ebay required to access the ebay API
  2. Create a new shortlived user access token by providing a valid refresh token

This set represents a short-lived access token (2 hours) and an accompanying refresh token that can be used to request further access tokens.

  1. Download orders (This includes cancelled orders)

Quick start

Define the following env variables

# EBAY_ACCESS_TOKEN_SERVICE=https://api.ebay.com/identity/v1/oauth2/token
EBAY_CLIENT_ID=Your ebay client id
EBAY_CLIENT_SECRET=Your ebay client secret
import { getUserAccessToken } from '@chanoch/ebay-api-client'

const authTokenSet = getUserAccessToken(authCode)

Ebay Auth Flow Overview

The ebay developer programme (https://developer.ebay.com/) allows access to an ebay seller's orders given the seller's authorisation. It uses an OAuth2 flow:

  • Application directs the user to an ebay login page (providing an optional xsrf token in the form of a GET request URL parameter)
  • User authorises applicaton to access their data
  • Ebay redirects the user to an accept page providing an authorisation code
  • The applications checks the xsrf token and captures the code
  • The application exchanges the code for an authentication token set including a short lived auth token and a long lived refresh token
  • The application uses the auth token to request data

You need to sign up to a developer account with ebay. (https://developer.ebay.com) Adding an application will generate an application key pair which includes:

  • RuName (aka Redirect URI)

These can be found at https://developer.ebay.com/my/keys

The redirect uri is a code similar to the client id and secret which identities the URL to redirect users to on your application. This value must be over a secure TLS connection.

These need to be provided in each request to the API

User Access Token - grant_type=authorization_code

The json returned from the getAccessToken function is as follows (copied from ebay site). Expiry is in seconds (2 hours for access token, 18 months for the refresh token)

    "access_token": "v^1.1#i^1#p^3#r^1...XzMjRV4xMjg0",
    "expires_in": 7200,
    "refresh_token": "v^1.1#i^1#p^3#r^1...zYjRV4xMjg0",
    "refresh_token_expires_in": 47304000,
    "token_type": "User Access Token"

User Access Token - grant_type=refresh_token

The json returned from the refreshAccessToken:

    "access_token": "v^1.1#i ... AjRV4yNjA=",
    "expires_in": 7200,
    "token_type":"User Access Token"

Retrieve unfulfilled orders

Pass in a date to get all unfulfilled orders since this date. This allows you to create a cron job to retrieve new orders since a given datatime watermark

ENV Variables

  • EBAY_ORDERS_DOWNLOAD_PAGE_SIZE - this determines the page size for retrieving orders. This will retrieve all orders but in pages of EBAY_ORDERS_DOWNLOAD_PAGE_SIZE (default 50)
  • EBAY_ORDERS_ENDPOINT - the ebay api endpoint for retrieving oders. probably https://api.ebay.com/sell/fulfillment/v1/order

Configuration via Env variables

The library is configured via env vars. Defined the following variables:

  • EBAY_CLIENT_ID = the ebay client id
  • EBAY_CLIENT_SECRET = the ebay client secret
  • EBAY_REDIRECT_URI - redirect uri (aka application RuName)
  • EBAY_ACCESS_TOKEN_SERVICE - the oauth2 end point (probably https://api.ebay.com/identity/v1/oauth2/token)


The requirement for the oauth flow to be over https even for the test sandbox, you might want to create a test harness that doubles as the ebay api during dev/test and for test automation

It is tempting to fully automate the test harness but you might find you need the control of manual intervention during early development. Put in a switch (probably in the form of a request param) that allows you to slow things down by requiring user action to 'authorise' the next step in the flow.

Release notes

1.2.1 Download based on modified data, not created date.

As the ebay seller site allows sellers to cancel orders and generally manage them, rather than downloading unfulfilled orders only by create date (essentially fetching all new orders), it now downloads all orders modified since the date given. (if a date is not given, the client will download unfulfilled orders in last 30 days)

This allows you to detect orders which have been modified outside of your system.

Other changes:

  1. Changed default page size to 200 from 50