These docs are for v1.1. Click to read the latest docs for v1.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.


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:

data-partner-keyYour public API key given to you when your ShippingEasy partner account was created.
data-tokenA 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-ship-from-name="ShippingEasy Inc."
  data-ship-from-address="609 Castle Ridge Rd"
  data-ship-to-company="Acme Inc"
  data-ship-to-address="7500 Happy Lane"
  data-ship-to-email="[email protected]"

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.

data-order-numberThe unique order identifier from your system.
data-ship-from-nameName of the person or company sending the package.
data-ship-from-addressThe sender's street address.
data-ship-from-address2Additional field for the sender's street address.
data-ship-from-cityThe sender's city
data-ship-from-stateThe sender's state
data-ship-from-provinceThe sender's province
data-ship-from-postal-codeThe sender's postal code
data-ship-from-postal-code-plus-4The sender's postal code plus 4
data-ship-from-postal-code-overrideOptional origin postal code (USPS only)
data-ship-from-countryThe sender's country
data-ship-from-emailThe sender's email address
data-ship-from-phone-numberThe sender's phone number
Set to true if the sender's address is residential, false if address is commercial
data-ship-to-first-nameFirst name of recipient.
data-ship-to-last-nameLast name of the recipient.
data-ship-to-companyName of the recipient's company.
data-ship-to-addressThe recipient's street address.
data-ship-to-address2Additional field for the recipient's street address.
data-ship-to-cityThe recipient's city
data-ship-to-stateThe recipient's state if address is domestic
data-ship-to-provinceThe recipient's province if address is international
data-ship-to-postal-codeThe recipient's postal code
data-ship-to-postal-code-plus-4The recipient's postal code plus 4
data-ship-to-countryThe recipient's country
data-ship-to-emailThe recipient's email address
data-ship-to-phone-numberThe recipient's phone number
Set to true if the recipient's address is residential, false if address is commercial
The number of pounds the order weighs.
data-ouncesInteger or Float
The number of ounces the order weighs.

Required for each line item.

The quantity of the nth line item.

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.

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 = "";
    url: "/tokens",
    type: "post",
    dataType: "json",
    data: { "order_number": orderNumber }
  }).done(function(data) {
      $token = data.token;
  return $token;