Have ideas to improve npm?Join in the discussion! »

    TypeScript icon, indicating that this package has built-in type declarations

    0.7.2 • Public • Published



    NodeJs Etsy ReST API Client.

    • compatible with JavaScript and TypeScript.


    • findAllShops
    • getShop
    • findAllShopSections
    • findAllShopListingsActive
    • getListing
    • getVariationImages
    • findAllListingImages
    • getInventory
    • getAttributes
    • getProduct
    • findAllListingShippingProfileEntries

    Quick start

    First declare your api key :

    export ETSY_API_KEY=xxxxxxxxxxx

    install node-etsy-client

    npm install node-etsy-client

    then let's go, here is a sample.js:

    const EtsyClient = require('node-etsy-client')
    async function doIt() {
      var client = new EtsyClient();
      var shops = await client.getShops({'limit':10});

    You could play mocha tests to get more examples (cf. next section).

    You could avoid using environment variable by using constructor options:

    var client = new EtsyClient({apiKey:'mSecretHere'});

    Advanced usage

    Etsy client options

    This section describes EtsyClient available options.

    Note about options precedence: first take option value from constructor if any, or else try to retrieve related environment variable, or else apply default value.

    • apiUrl : Etsy api endpoint - required (or env.ETSY_API_ENDPOINT) default value is https://openapi.etsy.com/v2.
    • apiKey : Etsy api key - required (or env.ETSY_API_KEY) without default value. Ask one from Etsy portal
    • shop : Etsy shop name - optional (or env.ETSY_SHOP) without default value.
    • lang : Etsy language - optional (or env.ETSY_LANG) without default value. Example: fr
    • etsyRateWindowSizeMs : Rate limit windows size in milliseconds - optional (or env.ETSY_RATE_WINDOWS_SIZE_MS) with default value: 1000
    • etsyRateMaxQueries : Rate limit max query per windows size - optional (or env.ETSY_RATE_MAX_QUERIES) without default value
    • dryMode : print call instead of making real etsy call - optional (or env.ETSY_DRY_MODE) with default value: false

    Note about rate limit options:

    Rate limit is enabled if and only if etsyRateWindowSizeMs and etsyRateMaxQueries are both set.

    This will configure rate limit on etsy call : max etsyRateMaxQueries per etsyRateWindowSizeMsms.

    For more details, cf. susi-rali

    Rate limit

    According to their documentation, Etsy restricts number of call to 10 per second (and 10k per day).

    In order to never reach this (second windows) rate limit, node-etsy-client rely on susi-rali and offer an option to rate limit client calls.

    To apply rate limit of 10 query per seconds (with wait on unavailable slot), add etsyRateMaxQueries option:

    var client = new EtsyClient({apiKey:'mSecretHere', etsyRateMaxQueries:10});

    How to contribute

    You're not a dev ? just submit an issue (bug, improvements, questions). Or else:

    • Clone
    • Install deps
    • setup your test environment (cf. initEnv.example.sh)
    • Then mocha tests
    git clone https://github.com/creharmony/node-etsy-client.git
    cd node-etsy-client
    npm install
    # play test without etsy endpoint
    npm run test
    # play test with etsy endpoint
    . ./env/initEnv.example.sh
    npm run test
    • you could also fork, feature branch, then submit a pull request.

    Services or activated bots

    badge name description
    CI/CD Github actions Continuous tests.
    scheduled npm audit Github actions Continuous vulnerability audit.
    Houndci JavaScript automated review (configured by .hound.yml)
    Automated Release Notes by gren gren Release notes automation


    npm i node-etsy-client

    DownloadsWeekly Downloads






    Unpacked Size

    36.6 kB

    Total Files


    Last publish


    • avatar