Step by Step Guide to Building a Shippo API Integration in JS

Sep 14, 2024 • 6 minute read

Introduction

Hey there, fellow developer! Ready to dive into the world of shipping APIs? Today, we're going to walk through integrating the Shippo API into your JavaScript project. Shippo's a fantastic tool for handling all things shipping, and with their handy shippo package, we'll have this integration up and running in no time.

Prerequisites

Before we jump in, make sure you've got:

Node.js and npm installed (I know you probably do, but just checking!)
A Shippo account and API key (grab one at shippo.com if you haven't already)

Setting up the project

Let's kick things off by setting up our project:

mkdir shippo-integration
cd shippo-integration
npm init -y
npm install shippo

Configuring Shippo client

Now, let's get that Shippo client configured:

const Shippo = require('shippo');

const shippo = Shippo('your_api_key_here');

Easy peasy, right? Just remember to keep that API key secret!

Creating an address

Time to create some addresses. Here's how you'd set up sender and recipient addresses:

const addressFrom = {
  name: 'Shawn Ippotle',
  street1: '215 Clayton St.',
  city: 'San Francisco',
  state: 'CA',
  zip: '94117',
  country: 'US'
};

const addressTo = {
  name: 'Mr. Hippo',
  street1: '1092 Indian Summer Ct',
  city: 'San Jose',
  state: 'CA',
  zip: '95122',
  country: 'US'
};

Creating a parcel

Next up, let's define our parcel:

const parcel = {
  length: '5',
  width: '5',
  height: '5',
  distance_unit: 'in',
  weight: '2',
  mass_unit: 'lb'
};

Getting shipping rates

Now for the fun part - let's get those shipping rates:

shippo.shipment.create({
  address_from: addressFrom,
  address_to: addressTo,
  parcels: [parcel],
  async: false
})
.then(shipment => {
  console.log(shipment.rates);
})
.catch(error => {
  console.error('Error:', error);
});

Creating a shipment

Creating a shipment is just as straightforward:

shippo.shipment.create({
  address_from: addressFrom,
  address_to: addressTo,
  parcels: [parcel],
  async: false
})
.then(shipment => {
  console.log('Shipment created:', shipment.object_id);
})
.catch(error => {
  console.error('Error:', error);
});

Purchasing a label

Ready to buy that label? Here's how:

shippo.transaction.create({
  shipment: shipmentId,
  carrier_account: carrierId,
  service_level_token: serviceLevel
})
.then(transaction => {
  console.log('Label URL:', transaction.label_url);
})
.catch(error => {
  console.error('Error:', error);
});

Tracking a shipment

Let's not forget about tracking:

shippo.track.get_status('SHIPPO_TRANSIT', 'usps')
.then(status => {
  console.log('Tracking status:', status.tracking_status);
})
.catch(error => {
  console.error('Error:', error);
});

Error handling

Always remember to handle those pesky errors:

.catch(error => {
  if (error.type === 'ShippoAPIError') {
    console.error('Shippo API Error:', error.message);
  } else {
    console.error('Unexpected Error:', error);
  }
});

Webhooks (optional)

Want real-time updates? Shippo's got you covered with webhooks. Just set up an endpoint in your app to receive POST requests from Shippo, and you're good to go!

Conclusion

And there you have it! You've just built a Shippo API integration in JavaScript. Pretty cool, huh? Remember, this is just scratching the surface. Shippo's API is packed with features, so don't be afraid to explore and experiment.

Resources

Now go forth and ship with confidence! Happy coding!