Courier Pick Ups
Once you have confirmed shipments and labels, you can interact with couriers to understand the pickup services they provide, schedule courier collections, or mark an item as handed over (in the case the courier doesn't offer pick ups or you already have regular collections at your premesis).
Users with regular collections
If you already have regular collections taking place at your, or your client's warehouse, you don't need to request a collection, you can instead skip ahead to marking an item as directly handed over
Retrieve Available Collection Slots
You're able to use the pickup_slots resources at the /pickups endpoint, to retrieve a list of available collection slots for a selected courier, for the next 7 days.
To specify the courier, you can add the selected courier_id as a parameter in your request.
For example, you would send a GET request to:
https://api.easyship.com/pickup/v1/pickup_slots/b4552ed2-ae95-4647-9746-5790bf252c7f
curl --include \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
'https://api.easyship.com/pickup/v1/pickup_slots/{courier_id}'
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/pickup/v1/pickup_slots/{courier_id}', headers
puts response
var request = require('request');
request({
method: 'GET',
url: 'https://api.easyship.com/pickup/v1/pickup_slots/{courier_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/pickup/v1/pickup_slots/{courier_id}', headers=headers)
response_body = urlopen(request).read()
print response_body
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/pickup/v1/pickup_slots/{courier_id}");
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);
var request = new XMLHttpRequest();
request.open('GET', 'https://api.easyship.com/pickup/v1/pickup_slots/{courier_id}');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Bearer <YOUR EASYSHIP API TOKEN>');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
request.send();
The courier_id can be found by call
An example response below:
{
"courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
"courier_name": "UPS",
"message": "This Courier provides a pickup service. The available time slots are shown in local time, for the coming 7 days.",
"pickup": {
"provider_name": "UPS",
"provider_customer_service_phone": "+1 2345 6789",
"slots": {
"2017-04-25": [
{
"min_time": 17,
"max_time": 21
}
],
"2017-04-26": [
{
"min_time": 10,
"max_time": 13
},
{
"min_time": 13,
"max_time": 17
},
{
"min_time": 17,
"max_time": 21
}
],
"2017-04-27": [
{
"min_time": 10,
"max_time": 13
},
{
"min_time": 13,
"max_time": 17
},
{
"min_time": 17,
"max_time": 21
}
],
"2017-04-28": [
{
"min_time": 10,
"max_time": 13
},
{
"min_time": 13,
"max_time": 17
},
{
"min_time": 17,
"max_time": 21
}
],
"2017-04-29": [
{
"min_time": 10,
"max_time": 13
},
{
"min_time": 13,
"max_time": 17
}
],
"2017-04-30": [],
"2017-05-01": [
{
"min_time": 10,
"max_time": 13
},
{
"min_time": 13,
"max_time": 17
},
{
"min_time": 17,
"max_time": 21
},
{
"min_time": 23,
"max_time": 24
}
]
}
}
}
Book A Collection
Once you've retrieved the collection slots of a given courier, you can now select your preferred slot and book a collection. You'll need to include the courier_id, preferred_date, preferred_min_time, preferred_max_time and the easyship_shipment_ids
When making this request, we will confirm this directly with the courier.
First, you need to make a POST request to /pickup/v1/pickups
{
"courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
"preferred_date": "2016-12-08",
"preferred_max_time": "2016-12-08T18:00",
"preferred_min_time": "2016-12-08T09:00",
"easyship_shipment_ids": [
"ESUS3171766"
]
}
curl --include \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
--data-binary "{
\"courier_id\": \"b4552ed2-ae95-4647-9746-5790bf252c7f\",
\"preferred_date\": \"2016-12-08\",
\"preferred_max_time\": \"2016-12-08T18:00\",
\"preferred_min_time\": \"2016-12-08T09:00\",
\"easyship_shipment_ids\": [
\"ESUS3171766\"
]
}" \
'https://api.easyship.com/pickup/v1/pickups'
var request = require('request');
request({
method: 'POST',
url: 'https://api.easyship.com/pickup/v1/pickups',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
},
body: "{ \"courier_id\": \"b4552ed2-ae95-4647-9746-5790bf252c7f\", \"preferred_date\": \"2016-12-08\", \"preferred_max_time\": \"2016-12-08T18:00\", \"preferred_min_time\": \"2016-12-08T09:00\", \"easyship_shipment_ids\": [ \"ESUS3171766\" ]}"
}, 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 = '{
"courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
"preferred_date": "2016-12-08",
"preferred_max_time": "2016-12-08T18:00",
"preferred_min_time": "2016-12-08T09:00",
"easyship_shipment_ids": [
"ESUS3171766"
]
}'
headers = {
:content_type => 'application/json',
:authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}
response = RestClient.post 'https://api.easyship.com/pickup/v1/pickups', values, headers
puts response
from urllib2 import Request, urlopen
values = """
{
"courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
"preferred_date": "2016-12-08",
"preferred_max_time": "2016-12-08T18:00",
"preferred_min_time": "2016-12-08T09:00",
"easyship_shipment_ids": [
"ESUS3171766"
]
}
"""
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
}
request = Request('https://api.easyship.com/pickup/v1/pickups', data=values, headers=headers)
response_body = urlopen(request).read()
print response_body
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/pickup/v1/pickups");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
\"courier_id\": \"b4552ed2-ae95-4647-9746-5790bf252c7f\",
\"preferred_date\": \"2016-12-08\",
\"preferred_max_time\": \"2016-12-08T18:00\",
\"preferred_min_time\": \"2016-12-08T09:00\",
\"easyship_shipment_ids\": [
\"ESUS3171766\"
]
}");
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);
var request = new XMLHttpRequest();
request.open('POST', 'https://api.easyship.com/pickup/v1/pickups');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Bearer <YOUR EASYSHIP API TOKEN>');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
var body = {
'courier_id': 'b4552ed2-ae95-4647-9746-5790bf252c7f',
'preferred_date': '2016-12-08',
'preferred_max_time': '2016-12-08T18:00',
'preferred_min_time': '2016-12-08T09:00',
'easyship_shipment_ids': [
'ESUS3171766'
]
};
request.send(JSON.stringify(body));
After successfully making the request, the response will contain a pickup_reference_number, which you can use in your customer service correspondence with the courier.
{
"courier_id": "b4552ed2-ae95-4647-9746-5790bf252c7f",
"courier_name": "UPS",
"easyship_shipment_ids": [
"ESUS3171766"
],
"pickup":
{
"easyship_pickup_id": "PHK0000001",
"preferred_min_time": "2016-12-08T09:00",
"preferred_max_time": "2016-12-08T18:00",
"pickup_reference_number": "292494AGF4L",
"pickup_fee": "0.0",
"provider_name": "UPS",
"provider_customer_service_phone": "+1 2345 6789",
"shipments_count": "1",
"total_actual_weight": "1.0",
"pickup_state": "requested",
"address":
{
"line_1": "123 Test Street",
"line_2": "Block 3",
"line_3": "Unit 1000",
"postal_code": "ABC123",
"city": "Hong Kong",
"state": null,
"country": "Hong Kong",
"contact_email": "[email protected]",
"contact_phone": "+852-1234-5678",
"company_name": "Test Plc.",
"contact_name": "Foo Bar",
}
}
}
Once the collection is completed, this will trigger an update of the tracking status.
Marking an Item as Directly Handed Over
This is an alternative to requesting a collection. If your selected courier doesn't offer a collection service and you instead drop off to their location, or if you already have regular collections scheduled with a courier at your warehouse.
To mark items as directly handed over, you need to issue a POST request to https://api.easyship.com/pickup/v1/direct_handover, and include the easyship_shipment_ids.
{
"easyship_shipment_ids": [
"ESUS3171766"
]
}
curl --include \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <YOUR EASYSHIP API TOKEN>" \
--data-binary "{
\"easyship_shipment_ids\": [
\"ESUS3171766\"
]
}" \
'https://api.easyship.com/pickup/v1/direct_handover'
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '{
"easyship_shipment_ids": [
"ESUS3171766"
]
}'
headers = {
:content_type => 'application/json',
:authorization => 'Bearer <YOUR EASYSHIP API TOKEN>'
}
response = RestClient.post 'https://api.easyship.com/pickup/v1/direct_handover', values, headers
puts response
var request = require('request');
request({
method: 'POST',
url: 'https://api.easyship.com/pickup/v1/direct_handover',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
},
body: "{ \"easyship_shipment_ids\": [ \"ESUS3171766\" ]}"
}, 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
values = """
{
"easyship_shipment_ids": [
"ESUS3171766"
]
}
"""
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer <YOUR EASYSHIP API TOKEN>'
}
request = Request('https://api.easyship.com/pickup/v1/direct_handover', data=values, headers=headers)
response_body = urlopen(request).read()
print response_body
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.easyship.com/pickup/v1/direct_handover");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
\"easyship_shipment_ids\": [
\"ESUS3171766\"
]
}");
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);
var request = new XMLHttpRequest();
request.open('POST', 'https://api.easyship.com/pickup/v1/direct_handover');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Bearer <YOUR EASYSHIP API TOKEN>');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
var body = {
'easyship_shipment_ids': [
'ESUS3171766'
]
};
request.send(JSON.stringify(body));
You will receive a response acknowledging the update, and this is the trigger to update the tracking status, and now you can send the tracking information to the end customer
{
"direct_handover": {
"easyship_shipment_ids": [
"ESUS3171766"
],
"pickup_state": "completed"
}
}
Updated over 6 years ago
What’s Next