EasyPost Node Client Library


10934.0.019 days ago5 years agoMinified + gzip package size for @easypost/api in KB


EasyPost Node Client Library

EasyPost is a simple shipping API. You can sign up for an account at https://easypost.com.

CI npm version


npm install --save @easypost/api

Note: if you are using a version of Node less than 6.9, you will need to install and include a polyfill, such as babel-polyfill, and include it in your project:

npm install --save babel-polyfill

In your file:

const EasyPost = require('@easypost/api');

You can alternatively download the various built assets from this project's releases page.


By default, @easypost/api works with Node v6 LTS. To include for other versions of node, you can use:

  • require('@easypost/api/easypost.8-lts.js') (Node 8.9+)
  • require('@easypost/api/easypost.6-lts.js') (Node 6.9+)
  • require('@easypost/api/easypost.legacy.js') (Node 0.10+)


const EasyPost = require('@easypost/api');

const api = new EasyPost('API_KEY');

const shipment = new api.Shipment({
  to_address: {
    name: 'Dr. Steve Brule',
    street1: '179 N Harbor Dr',
    city: 'Redondo Beach',
    state: 'CA',
    zip: '90277',
    country: 'US',
    phone: '4155559999',
  from_address: {
    street1: '417 MONTGOMERY ST',
    street2: 'FLOOR 5',
    city: 'SAN FRANCISCO',
    state: 'CA',
    zip: '94104',
    country: 'US',
    company: 'EasyPost',
    phone: '415-123-4567',
  parcel: {
    length: 8,
    width: 5,
    height: 5,
    weight: 5
  customs_info: {
    eel_pfc: 'NOEEI 30.37(a)',
    customs_certify: true,
    customs_signer: 'Steve Brule',
    contents_type: 'merchandise',
    contents_explanation: '',
    restriction_type: 'none',
    restriction_comments: '',
    non_delivery_option: 'abandon',
    declaration: 'Here is a bunch of information...',

    customs_items: [
      new api.CustomsItem({
        'description': 'Sweet shirts 1',
        'quantity': 2,
        'weight': 11,
        'value': 23,
        'hs_tariff_number': '654321',
        'origin_country': 'US',
        'code': '123'

shipment.save().then(s => s.buy(shipment.lowestRate()).then(console.log).catch(console.log))


You can construct an API instance with certain options:

const api = new Api("mykey", {
  timeout: 120000,
  baseUrl: "https://api.easypost.com/v2/",
  useProxy: false,
  superagentMiddleware: s => s,
  requestMiddleware: r => r,


Time in milliseconds that should fail requests.


Change the base URL that the API library uses. Useful if you proxy requests from a frontend through a server.


Disable using the API key. Useful if you proxy requests from a frontend through a server.


Function that takes superagent and returns superagent. Useful if you need to wrap superagent in a function, such as many superagent libraries do.

import superagentLib from 'some-superagent-lib';

const api = new Api("my-key", {
  superagentMiddleware: s => superagentLib(s),


Function that takes a superagent request and returns that request. Useful if you need to hook into a request:

import superagentLib from 'some-superagent-lib';

const api = new Api("my-key", {
  requestMiddleware: r => {
    return r;


To test out the API, you can run the following:

npm install -g @easypost/api

Install Dependencies

npm install


Build the various versions of the client library by running the following:

npm run build


Run unit tests by running the following:

npm test

Interactive CLI

Replace easypost.js with whatever compatabile version you wish, as defined under Compatibility.

API_KEY=yourkey ./repl.js --local easypost.js


  1. Update the version in the package.json file
  2. Update the CHANGELOG file
  3. Tag the release on GitHub
  4. Upload the built assets from npm run build to the new GitHub release (eg: easypost.js, easypost.6-lts.js, etc)
  5. Publish the npm package with npm publish (this will build the project and run tests as a part of the process)

Note on ES6 Usage

You can import specific versions of the compiled code if you're using later versions of Node.

// Imports the un-transformed es6
import "@easypost/api/src/easypost"

// Use the following to import mininally transformed versions
import "@easypost/api/easypost.6-lts"
import "@easypost/api/easypost.8-lts"
import "@easypost/api/easypost.legacy.js" // (v0.10)

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.