Hey! These docs are for version 1.1, which is no longer officially supported. Click here for the latest version, 1.2!

EasyShip is a simple, embeddable shipping widget that provides a fully managed label printing solution within e-commerce platforms or marketplaces. It allows merchants to seamlessly generate shipping labels and fulfill e-commerce orders with minimal development effort.

Prerequisites

You'll need an official ShippingEasy Partner account before integrating the EasyShip widget into your codebase. Contact [email protected] if your company would like to become a partner.

1. Include the script tag

You can integrate EasyShip with a minimal amount of client-side code. First you will need to include the EasyShip javascript library, initialized with a few configuration options.

Here's the simplest configuration, setting the session token on the script tag. In this case the token is shared for all EasyShip triggers on the page:

<script
  src="https://app.shippingeasy.com/easyship.js"
  data-partner-key="XXX"
  data-token="dc02eec82448924a6a8d0ad4a1174af41e342fc2d45962e702ac137bd">
</script>

Atrtibute

Description

data-partner-key

Your public API key given to you when your ShippingEasy partner account was created.

data-token

A special, time-limited session token that you generate on your server and pass down to the client-side code when rendering the page. This is not needed if you write your own custom token function and assign it to EasyShip.

2. Create an EasyShip button or link

Next, you will need to create a trigger to initialize the EasyShip modal for each order on your page. Here's an example of attaching EasyShip behavior to a button:

<button class="easyship-trigger"
  data-order-number="XXX123"
  data-ship-from-name="ShippingEasy Inc."
  data-ship-from-address="609 Castle Ridge Rd"
  data-ship-from-city="Austin"
  data-ship-from-state="TX"
  data-ship-from-postal-code="78746"
  data-ship-from-postal-code-override="99501"
  data-ship-from-country="USA"
  data-ship-from-phone-number="512-699-4421"
  data-ship-to-first-name="Theo"
  data-ship-to-last-name="Mills"
  data-ship-to-company="Acme Inc"
  data-ship-to-address="7500 Happy Lane"
  data-ship-to-city="Austin"
  data-ship-to-state="TX"
  data-ship-to-postal-code="78701"
  data-ship-to-country="USA"
  data-ship-to-email="[email protected]"
  data-ship-to-phone-number="512-777-1234"
  data-ship-to-residential=true
  data-line-item-description-1="Socks"
  data-line-item-quantity-1="1"
  data-line-item-value-cents-1="1000"
  data-line-item-weight-in-ounces-1="16"
  data-line-item-country-of-manufacture-1="USA"
  data-pounds="1"
  data-ounces="3">EasyShip</button>

The data attributes include details about the order that is ready to be shipped and are used to pre-populate the shipment form inside the EasyShip modal. The "easyship-trigger" class on the element adds an on-click event to trigger the EasyShip modal.

Attribute

Description

data-order-number

The unique order identifier from your system.

data-ship-from-name

Name of the person or company sending the package.

data-ship-from-address

The sender's street address.

data-ship-from-address2

Additional field for the sender's street address.

data-ship-from-city

The sender's city

data-ship-from-state

The sender's state

data-ship-from-province

The sender's province

data-ship-from-postal-code

The sender's postal code

data-ship-from-postal-code-plus-4

The sender's postal code plus 4

data-ship-from-postal-code-override

Optional origin postal code (USPS only)

data-ship-from-country

The sender's country

data-ship-from-email

The sender's email address

data-ship-from-phone-number

The sender's phone number

data-ship-from-residential

Boolean
Set to true if the sender's address is residential, false if address is commercial

data-ship-to-first-name

First name of recipient.

data-ship-to-last-name

Last name of the recipient.

data-ship-to-company

Name of the recipient's company.

data-ship-to-address

The recipient's street address.

data-ship-to-address2

Additional field for the recipient's street address.

data-ship-to-city

The recipient's city

data-ship-to-state

The recipient's state if address is domestic

data-ship-to-province

The recipient's province if address is international

data-ship-to-postal-code

The recipient's postal code

data-ship-to-postal-code-plus-4

The recipient's postal code plus 4

data-ship-to-country

The recipient's country

data-ship-to-email

The recipient's email address

data-ship-to-phone-number

The recipient's phone number

data-ship-to-residential

Boolean
Set to true if the recipient's address is residential, false if address is commercial

data-pounds

Integer
The number of pounds the order weighs.

data-ounces

Integer or Float
The number of ounces the order weighs.

data-line-item-quantity-[1..5]

Integer

Required for each line item.

The quantity of the nth line item.

data-weight-in-ounces-[1..5]

Integer

Required for each line item.

The number of ounces that the nth line item weighs. Note that the sum of all line items should match the order's total weight.

data-line-item-value-cents-[1..5]

Integer

Required for each line item.

The value of the nth line item in cents. E.g. $1.00 would be represented as "100".

data-line-item-description-[1..5]

Required for each line item.

The description or item name of the nth line item.

data-line-item-country-of-manufacture-[1..5]

The country in which the item was manufactured. This is needed for customs forms if the order is international. Defaults to "United States" if not specified.

📘

Line items

Line items are only needed if the order is international, because they are used to generate a customs form for the shipment.

3. Generate a session token from your server

In order to authenticate the Ajax calls coming from the the client-side EasyShip modal, a session token must first be generated on your server. Session tokens are generated using our REST partner API and require that you first have a Parter API key and API secret. The token is included in the Javascript configuration options, as detailed in "Client-side setup".

Our API calls require that the request be signed using your key and secret. The session token call also requires that a "customer identifier" is included so that we can associate specific EasyShip sessions with a customer in your system. This identifier should be unique to your system, as it will be used to reconcile label purchases made against your partner account.

Session tokens can be created to live from 5 seconds to 30 minutes and may be marked as single use to ensure every request is freshly authenticated.

Custom token function

It is possible to write your own token function that will be executed before every EasyShip request. There are several benefits to taking this approach:

  • To create short-lived, single-use tokens, increasing the security of your EasyShip communications
  • Preventing a session token from expiring as a user waits on a page

Ideally this function would make a remote request to a token generating endpoint on your server. Here's is an example:

EasyShip.token = function (orderNumber) {
  var $token = "";
  $.ajax({
    url: "/tokens",
    type: "post",
    dataType: "json",
    async:false,
    data: { "order_number": orderNumber }
  }).done(function(data) {
      $token = data.token;
    }
  );
  return $token;
}