Retrieve, Update and Delete Shipments
The Easyship API is versatile for retrieving and updating shipment information
Using the shipment endpoint, you're able to pull down, update and delete shipments that exist within an Easyship account.
Retrieving a List of Shipments
You're able to make a call to the shipment end point to pull down existing shipments. You can filter this request using a number of parameters like the platform it was generated on, or a single order number. For this scenario, we'll search for valid orders, after a certain point in time, using the shipment_state and created_at_from URL parameters.
Retrieving Confirmed Shipments
When you issue
GETrequest to theshipment/v1/shipmentsresource with aneasyship_shipment_idthat has already been confirmed and had a label purchased, we will also return within the response:
label_state
label_url
tracking_number
tracking_page_url
curl --include \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page='
var request = require('request');
request({
method: 'GET',
url: 'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
}}, function (error, response, body) {
console.log('Status:', response.statusCode);
console.log('Headers:', JSON.stringify(response.headers));
console.log('Response:', body);
});
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
headers = {
:content_type => 'application/json',
:authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}
response = RestClient.get 'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=', headers
puts response
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
headers = {
:content_type => 'application/json',
:authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}
response = RestClient.get 'https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=', headers
puts response
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/shipment/v1/shipments?easyship_shipment_id=&platform_order_number=&shipment_state=&pickup_state=&delivery_state=&label_state=&created_at_from=&created_at_to=&confirmed_at_from=&confirmed_at_to=&per_page=&page=");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Authorization: Bearer <YOUR EASYSHIP API TOKEN>"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
The response you receive will contain the data you need to create a pick and pack list:
{
"total_pages": 2,
"current_page": 1,
"shipments": [
{
"created_at": "2016-12-15T08:35:11.938Z",
"updated_at": "2016-12-15T08:35:12.079Z",
"easyship_shipment_id": "ESTEST00000",
"destination_name": "Aloha Chen",
"destination_address_line_1": "300 Park Avenue",
"destination_address_line_2": null,
"destination_city": "New York",
"destination_state": "NY",
"destination_postal_code": "10022",
"destination_phone_number": "+1 234-567-890",
"destination_email_address": "[email protected]",
"platform_order_number": "#1234",
"platform_name": "Amazon",
"total_customs_value": 100,
"total_actual_weight": 1.2,
"total_dimensional_weight": 0.6,
"total_volumetric_weight": 1.2,
"is_insured": false,
"currency": "SGD",
"origin_country": {
"name": "Singapore",
"alpha2": "SG"
},
"destination_country": {
"name": "United States",
"alpha2": "US"
},
"items": [
{
"id": "a918ff21-fe35-4cf0-bf48-a9ff5335d20e",
"description": "Silk dress",
"sku": "test",
"width": 15,
"length": 20,
"height": 10,
"actual_weight": 1.2,
"dimensional_weight": 0.6,
"volumetric_weight": 1.2,
"declared_customs_value": 100,
"declared_currency": "SGD",
"origin_customs_value": 100,
"origin_currency": "SGD",
"category": "fashion"
},
{
"id": "0f921583-26d4-4341-bce7-0995237ffa5c",
"description": "Cotton dress",
"sku": "test2",
"width": 15,
"length": 20,
"height": 10,
"actual_weight": 1.2,
"dimensional_weight": 0.6,
"volumetric_weight": 1.2,
"declared_customs_value": 100,
"declared_currency": "SGD",
"origin_customs_value": 100,
"origin_currency": "SGD",
"category": "fashion"
}
],
"box": {
"name": null,
"length": 20,
"width": 15,
"height": 10
},
"selected_courier": {
"id": "2a17f7aa-51f7-4d36-bca8-e77c164cb52a",
"name": "DHL Express",
"min_delivery_time": 2,
"max_delivery_time": 3,
"shipment_charge": 284.9,
"fuel_surcharge": 32.05125,
"remote_area_surcharge": 0,
"shipment_charge_total": 316.95125,
"warehouse_handling_fee": 0,
"insurance_fee": 0,
"import_tax_charge": 0,
"import_duty_charge": 0,
"ddp_handling_fee": 0,
"total_charge": 316.95,
"is_above_threshold": false,
"effective_incoterms": "DDU",
"estimated_import_tax": 0,
"estimated_import_duty": 0,
"courier_does_pickup": false,
"courier_dropoff_url": "https://www.easyship.com/drop-off/dhl/hk",
"courier_remarks": null,
"payment_recipient": "Easyship"
},
"rates": [
{
"courier_id": "462e4de9-0762-4c71-9cad-d6495ce364fb",
"courier_name": "DHL Express",
"min_delivery_time": 2,
"max_delivery_time": 3,
"value_for_money_rank": 1,
"delivery_time_rank": 1,
"shipment_charge": 68.082,
"fuel_surcharge": 8.51025,
"remote_area_surcharge": null,
"shipment_charge_total": 76.59225,
"warehouse_handling_fee": 0,
"insurance_fee": 0,
"ddp_handling_fee": 0,
"import_tax_charge": 0,
"import_duty_charge": 0,
"total_charge": 76.59,
"is_above_threshold": false,
"effective_incoterms": "DDU",
"estimated_import_tax": 0,
"estimated_import_duty": 0,
"courier_does_pickup": true,
"courier_dropoff_url": null,
"tracking_rating": 3,
"easyship_rating": 4.4
"courier_remarks": null,
"payment_recipient": "Easyship"
}
]
}
]
}
Multiple items are grouped into a single shipment by the platform_order_number. Within items, you will also receive the SKU (sku) with any quantities and you'll need to store the easyship_shipment_id to download or confirm the labels.
There are a number of parameters you can refine your searches by, see more in the API Reference .
Making Changes to Existing Shipments
You're able to make updates to existing shipments by making a PATCH request to the shipments resource, using the easyship_shipment_id as a URL parameter.
There are a number of attributes you can change and you include those within the body of your request
{
"platform_name": "Amazon",
"platform_order_number": "#1234",
"selected_courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
"destination_country_alpha2": "US",
"destination_city": "New York",
"destination_postal_code": "10022",
"destination_state": "NY",
"destination_name": "Aloha Chen",
"destination_address_line_1": "300 Park Avenue",
"destination_address_line_2": null,
"destination_phone_number": "+1 234-567-890",
"destination_email_address": "[email protected]",
"items": [
{
"description": "Silk dress",
"sku": "test",
"actual_weight": 1.2,
"height": 10,
"width": 15,
"length": 20,
"category": "fashion",
"declared_currency": "SGD",
"declared_customs_value": 100
}
]
}
curl --include \
--request PATCH \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
--data-binary "{
\"platform_name\": \"Amazon\",
\"platform_order_number\": \"#1234\",
\"selected_courier_id\": \"b8d528a7-a2d4-4510-a7ac-11cbbb6542cd\",
\"destination_country_alpha2\": \"US\",
\"destination_city\": \"New York\",
\"destination_postal_code\": \"10022\",
\"destination_state\": \"NY\",
\"destination_name\": \"Aloha Chen\",
\"destination_address_line_1\": \"300 Park Avenue\",
\"destination_address_line_2\": null,
\"destination_phone_number\": \"+1 234-567-890\",
\"destination_email_address\": \"[email protected]\",
\"items\": [
{
\"description\": \"Silk dress\",
\"sku\": \"test\",
\"actual_weight\": 1.2,
\"height\": 10,
\"width\": 15,
\"length\": 20,
\"category\": \"fashion\",
\"declared_currency\": \"SGD\",
\"declared_customs_value\": 100
}
]
}" \
'https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}'
var request = require('request');
request({
method: 'PATCH',
url: 'https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
},
body: "{ \"platform_name\": \"Amazon\", \"platform_order_number\": \"#1234\", \"selected_courier_id\": \"b8d528a7-a2d4-4510-a7ac-11cbbb6542cd\", \"destination_country_alpha2\": \"US\", \"destination_city\": \"New York\", \"destination_postal_code\": \"10022\", \"destination_state\": \"NY\", \"destination_name\": \"Aloha Chen\", \"destination_address_line_1\": \"300 Park Avenue\", \"destination_address_line_2\": null, \"destination_phone_number\": \"+1 234-567-890\", \"destination_email_address\": \"[email protected]\", \"items\": [ { \"description\": \"Silk dress\", \"sku\": \"test\", \"actual_weight\": 1.2, \"height\": 10, \"width\": 15, \"length\": 20, \"category\": \"fashion\", \"declared_currency\": \"SGD\", \"declared_customs_value\": 100 } ]}"
}, function (error, response, body) {
console.log('Status:', response.statusCode);
console.log('Headers:', JSON.stringify(response.headers));
console.log('Response:', body);
});
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '{
"platform_name": "Amazon",
"platform_order_number": "#1234",
"selected_courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
"destination_country_alpha2": "US",
"destination_city": "New York",
"destination_postal_code": "10022",
"destination_state": "NY",
"destination_name": "Aloha Chen",
"destination_address_line_1": "300 Park Avenue",
"destination_address_line_2": null,
"destination_phone_number": "+1 234-567-890",
"destination_email_address": "[email protected]",
"items": [
{
"description": "Silk dress",
"sku": "test",
"actual_weight": 1.2,
"height": 10,
"width": 15,
"length": 20,
"category": "fashion",
"declared_currency": "SGD",
"declared_customs_value": 100
}
]
}'
headers = {
:content_type => 'application/json',
:authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}
response = RestClient.patch 'https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}', values, headers
puts response
from urllib2 import Request, urlopen
values = """
{
"platform_name": "Amazon",
"platform_order_number": "#1234",
"selected_courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
"destination_country_alpha2": "US",
"destination_city": "New York",
"destination_postal_code": "10022",
"destination_state": "NY",
"destination_name": "Aloha Chen",
"destination_address_line_1": "300 Park Avenue",
"destination_address_line_2": null,
"destination_phone_number": "+1 234-567-890",
"destination_email_address": "[email protected]",
"items": [
{
"description": "Silk dress",
"sku": "test",
"actual_weight": 1.2,
"height": 10,
"width": 15,
"length": 20,
"category": "fashion",
"declared_currency": "SGD",
"declared_customs_value": 100
}
]
}
"""
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
}
request = Request('https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}', data=values, headers=headers)
request.get_method = lambda: 'PATCH'
response_body = urlopen(request).read()
print response_body
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
\"platform_name\": \"Amazon\",
\"platform_order_number\": \"#1234\",
\"selected_courier_id\": \"b8d528a7-a2d4-4510-a7ac-11cbbb6542cd\",
\"destination_country_alpha2\": \"US\",
\"destination_city\": \"New York\",
\"destination_postal_code\": \"10022\",
\"destination_state\": \"NY\",
\"destination_name\": \"Aloha Chen\",
\"destination_address_line_1\": \"300 Park Avenue\",
\"destination_address_line_2\": null,
\"destination_phone_number\": \"+1 234-567-890\",
\"destination_email_address\": \"[email protected]\",
\"items\": [
{
\"description\": \"Silk dress\",
\"sku\": \"test\",
\"actual_weight\": 1.2,
\"height\": 10,
\"width\": 15,
\"length\": 20,
\"category\": \"fashion\",
\"declared_currency\": \"SGD\",
\"declared_customs_value\": 100
}
]
}");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Authorization: Bearer <YOUR EASYSHIP API TOKEN>"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
As a response, you will receive a summary of the new information associated with the shipment, and an updated_at timestamp.
{
"shipment" => {
"created_at": "2016-11-23T04:52:24.559Z",
"updated_at": "2016-11-23T04:52:30.386Z",
"easyship_shipment_id": "ESHK2325803",
"destination_name": "Aloha Chen",
"destination_address_line_1": "300 Park Avenue",
"destination_address_line_2": null,
"destination_city": "New York",
"destination_state": "NY",
"destination_postal_code": "10022",
"destination_phone_number": "+1 234-567-890",
"destination_email_address": "[email protected]",
"platform_name": "Amazon",
"platform_order_number": "#1234",
"total_customs_value": 573.06,
"total_actual_weight": 1.2,
"total_dimensional_weight": 0.6,
"total_volumetric_weight": 1.2,
"is_insured": false,
"currency": "HKD",
"origin_country": {
"name": "Hong Kong",
"alpha2": "HK"
},
"destination_country": {
"name": "United States",
"alpha2": "US"
},
"items": [
{
"id": "00015b1f-0cda-4dc5-ae64-b920ff9f2d25",
"description": "Silk dress",
"sku": "test-123",
"width": 15.0,
"length": 20.0,
"height": 10.0,
"actual_weight": 1.2,
"dimensional_weight": 0.6,
"volumetric_weight": 1.2,
"declared_customs_value": 100.0,
"declared_currency": "SGD",
"origin_customs_value": 573.06,
"origin_currency": "HKD",
"category": "fashion"
}
],
"box": {
"name": null,
"length": 20,
"width": 15,
"height": 10
}
"selected_courier": {
"id": "2a17f7aa-51f7-4d36-bca8-e77c164cb52a",
"name": "DHL Express",
"min_delivery_time": 2,
"max_delivery_time": 3,
"shipment_charge": 284.9,
"fuel_surcharge": 32.05125,
"remote_area_surcharge": 0,
"shipment_charge_total": 316.95125,
"warehouse_handling_fee": 0,
"insurance_fee": 0,
"import_tax_charge": 0,
"import_duty_charge": 0,
"ddp_handling_fee": 0,
"total_charge": 316.95,
"is_above_threshold": false,
"effective_incoterms": "DDU",
"estimated_import_tax": 0,
"estimated_import_duty": 0,
"courier_does_pickup": false,
"courier_dropoff_url": "https://www.easyship.com/drop-off/dhl/hk",
"courier_remarks": null,
"payment_recipient": "Easyship"
},
"rates": [
{
"courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
"courier_name": "UPS",
"min_delivery_time": 1,
"max_delivery_time": 3,
"value_for_money_rank": 1.0,
"delivery_time_rank": 1.0,
"shipment_charge": 237.496,
"fuel_surcharge": 22.56212,
"remote_area_surcharge": 0,
"shipment_charge_total": 260.05812,
"warehouse_handling_fee": 0.0,
"insurance_fee": 0.0,
"ddp_handling_fee": 0.0,
"import_tax_charge": 0.0,
"import_duty_charge": 0.0,
"total_charge": 260.06,
"is_above_threshold": false,
"effective_incoterms": "DDU",
"estimated_import_tax": 0,
"estimated_import_duty": 0,
"courier_does_pickup": true,
"courier_dropoff_url": "",
"tracking_rating": 3.0,
"easyship_rating":4.3,
"courier_remarks": null,
"payment_recipient": "Easyship"
}
]
}
}
Deleting Shipments
If you need to delete a created shipment instead of updating it, you can call the shipments resource with a DELETE request, using the easyship_shipment_id as a parameter to define the shipment for deletion.
curl --include \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
'https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}'
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
headers = {
:content_type => 'application/json',
:authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}
response = RestClient.delete 'https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}', headers
puts response
var request = require('request');
request({
method: 'DELETE',
url: 'https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
}}, function (error, response, body) {
console.log('Status:', response.statusCode);
console.log('Headers:', JSON.stringify(response.headers));
console.log('Response:', body);
});
from urllib2 import Request, urlopen
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
}
request = Request('https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}', headers=headers)
request.get_method = lambda: 'DELETE'
response_body = urlopen(request).read()
print response_body
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/shipment/v1/shipments/{easyship_shipment_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Authorization: Bearer <YOUR EASYSHIP API TOKEN>"
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
For example:
DELETE /shipment/v1/shipments/ESHK0001785. You will receive the below as a response.
{
"status": "Shipment successfully deleted"
}
Updated almost 7 years ago
What’s Next
Specific attributes and data points are required to integrate with Easyship, you can use the Reference API to get these attributes to store.