Courier Pick Ups

🚧
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"
  }
}

🚧Users with regular collections

Retrieve Available Collection Slots

Book A Collection

Marking an Item as Directly Handed Over

🚧
Users with regular collections