August 20, 2024

EasyPost and Spree integration

EasyPost was founded in 2012 as the first RESTful API for shipping. The company has thousands of customers shipping millions of packages each month. It allows users to buy postage labels, check rates, verify an address, track their shipments, and more with all of the major shipping companies, including USPS, UPS, DHL, and FedEx.
The benefits of using EasyPost for your ecommerce business:

Modern Flexible Restful API

EasyPost gives you a modern, flexible RESTful API that connects to all the major carriers without the hassle and makes it easy to add shipping and tracking to your app.

Shipping API

Purchase shipping labels for USPS, UPS, FedEx, and 100+ other carriers

Tracking API

Track packages across all major carriers

Shipping Insurance

Shipping insurance for all items sent with EasyPost

Address verification

Validate domestic and international addresses

Rating API

Rate across all your carriers

Fulfillment

The tech-forward solution for all order fulfillment needs

Freight Shipping

Move freight via carriers offering competitive rates and enhanced supervision

International & Customs

Learn how to handle international shipping seamlessly

How to integrate EasyPost with Spree

Installation

Add this extension to your Gemfile with this line:

gem 'spree_easypost', github: 'ShopFelixGray/spree_easypost'

Install the gem using Bundler:

bundle install

Copy & run migrations

bundle exec rails g spree_easypost:install
rake db:migrate

This goes into a new file called config/initializers/easy_post.rb:

EasyPost.api_key = 'YOUR_API_KEY_HERE'

Restart your server

If your server was running, restart it so that it can find the assets properly.

Add Carrier Accounts

Make sure to add accounts (separated by commas but NO spaces) to the EasyPost settings in the admin section configuration. The account ids can be found in your EasyPost dashboard under the carrier section.

Usage

Validating An Address

To validate an address with this gem, call .easypost_address_validate on an instance of the Spree::Address model.

Example:

Spree::Address.find(1).easypost_address_validate

This method will not run the model validations that already exist in your application, nor will it save or update an address for you. This method is only designed to run the address through the EasyPost API and return a hash with suggestions to update the address if successful or return EasyPost error message is unsuccessful.

Response from the .easypost_address_validate method

This method will respond with a hash containing a key which will be either :suggestions (if the address is determined deliverable) or :errors (if the address is invalid or not deliverable).

Given the following address hash:

{
  firstname: "Bob",
  lastname: "Seger",
  address1: "624 W 139th St",
  address2: "Apt 2C",
  city: "New York",
  state_id: "3561",
  zipcode: "10031",
  country_id: "232",
  phone: "1234567890"
}

The suggestion hash will return the following – changing some of the formatting and moving address 2 to the address 1 line:

{
  suggestions: {
    address1: "624 W 139TH ST APT 2C",
    address2: "",
    city: "NEW YORK",
    zipcode: "10031-7329"
  }
}

Error responses from the .easypost_address_validate method

If the EasyPost API does not validate the address, you will receive an array of errors in the response hash.

Example error messages:

{
  errors: {
    address1: ["can't be blank"],
    address2: ["Missing secondary information(Apt/Suite#)"],
    address: [
      "Invalid city/state/ZIP",
      "Address not found"
    ]
  }
}

Errors will be returned under the address key if they are not particular to a specific part of the address such as when the address does not exist or if the error is related to multiple parts of the address (such as city/state/zip mismatch).

Testing

First bundle your dependencies, then run rake. rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using rake test_app.

bundle
bundle exec rake

When testing your applications integration with this extension you may use its factories. Simply add this require statement to your spec_helper:

require 'spree_easypost/factories'

Example of EasyPost and Spree integration

Felix Gray is a New York based producer of innovative glasses designed for healthier, happy eyes. Since the online store launched in 2016, hundreds of thousands of glasses have been sold. Felix Grays are worn in the offices of companies like Apple, Spotify, and Google. The company uses Spree to run a custom ecommerce platform and EasyPost for its shipping needs.