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;
}