Deliveries

Last updated 6 days ago

The new API v1.0 redefines the entity `TASK` renaming it to `Delivery`. We also redefined payloads, responses and endpoints. We'll introduce new helpers and functions that will enhance the c

In this document:

  • Create a new delivery

  • Cancel a delivery

  • Fetch delivery information

  • Fetch complete delivery information

  • Print Labels from deliveries

  • Final sample for creating delivery and generate pdf labels

Create a new delivery

POST /v1/deliveries

Description

In order to create a new delivery, you can either pre-select a quote with the time window that better fits your needs, or we'll create the new delivery for the next hour available.

flexible => You can set this parameter to true, when you'd like to create your deliveries with the next available flexible quotes. (Default: false, optional)

referenceId => Reference ID to index this delivery with an ID on your system, it can be an SKU or UPC. Used for integrations with other platforms (string, optional).

cod => Cash on delivery. Total amount charged by the shipper in cash, if the recipient did not pay before via bank transfer or credit card online. (float, optional)

quoteId => Quote generated beforehand with prices (integer, optional)

groupId => In case you need to group a list of deliveries, and later identify the batch created (string, optional)

curl
JavaScript
curl -X POST \
https://api.shippify.co/v1/deliveries/ \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/json' \
-d '{
"deliveries": [
{
"pickup": {
"contact": {
"name": "John Doe",
"email": "john@doe.com",
"phonenumber": "+19209489292"
},
"location": {
"address": "Central Park, New York, NY, United States",
"instructions": "Central Park West, APT 10920 "
}
},
"dropoff":{
"contact": {
"name": "Mary Doe",
"email": "mary@doe.co",
"phonenumber": "+19209085222"
},
"location": {
"address": "200 Eastern Pkwy, Brooklyn, NY 11238, USA",
"instructions": "APT 2094",
"lat": 40.6720036,
"lng": -73.9593279
}
},
"packages": [
{
"id": "B01LX1BBUS",
"name": "hat snapback",
"size": "xs",
"qty": 1
},
{
"id": "B071JD8VWG",
"name": "white shoes DC",
"size": "s",
"qty": 1
}
],
"referenceId": "INVOICE_1525909",
"cod": 100
}
],
["flexible": true || "quoteId": 142323],
"groupId": "7a901210-d46f-11e7-2018-01-01"
}'
var data = JSON.stringify({
"deliveries": [
{
"pickup": {
"contact": {
"name": "John Doe",
"email": "john@doe.com",
"phonenumber": "+19209489292"
},
"location": {
"address": "Central Park, New York, NY, United States",
"instructions": "Central Park West, APT 10920 "
}
},
"dropoff": {
"contact": {
"name": "Mary Doe",
"email": "mary@doe.co",
"phonenumber": "+19209085222"
},
"location": {
"address": "200 Eastern Pkwy, Brooklyn, NY 11238, USA",
"instructions": "APT 2094",
"lat": 40.6720036,
"lng": -73.9593279
}
},
"packages": [
{
"id": "B01LX1BBUS",
"name": "paperwork1",
"size": "xs",
"qty": 1
},
{
"id": "B071JD8VWG",
"name": "paperwork2",
"size": "xs",
"qty": 1
}
],
"referenceId": "INVOICE_1525909",
"cod": 100
}
],
["flexible": true || "quoteId": 142323 ],
"groupId": "7a901210-d46f-11e7-2018-01-01"
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.shippify.co/v1/deliveries/");
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXX");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);

Responses

200|Success

curl
JavaScript
{
message: "Delivery created successfully",
payload: {
currencyCode: "USD",
currencySign: "$",
distance: 4.5,
id: 't-shiinc-1523090',
price: 10.00,
cityId: 1
}
}
{
message: "Delivery created successfully",
payload: {
currencyCode: "USD",
currencySign: "$",
distance: 4.5,
id: 't-shiinc-1523090',
price: 10.00,
cityId: 1
}
}

400|Bad Request

curl
JavaScript
{
message: "Bad Request",
payload: { }
}
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

curl
JavaScript
{
message: "Error while retrieving the quote",
payload: { }
}
{
message: "Error while retrieving the quote",
payload: { }
}

Cancel a Delivery

POST /v1/deliveries/{:id}/cancel
curl
JavaScript
curl -X POST \
https://api.shippify.co/v1/deliveries/t-shieam-15853/cancel \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/json' \
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.shippify.co/v1/deliveries/t-shieam-15853/cancel");
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXXXXX");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);

Responses

200|Success

curl
JavaScript
{
message: "Delivery successfully canceled"
}
{
message: "Delivery successfully canceled"
}

400|Bad Request

curl
JavaScript
{
message: "Bad Request",
payload: { }
}
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

curl
JavaScript
{
message: "Error while canceling the delivery",
payload: { }
}
{
message: "Error while canceling the delivery",
payload: { }
}

Get a delivery by ID

GET /v1/deliveries/{:id}
curl
JavaScript
curl -X GET \
https://api.shippify.co/v1/deliveries/t-shieam-15853 \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/json' \
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.shippify.co/v1/deliveries/t-shieam-15853");
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXXXXX");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);

Responses

200|Success

curl
JavaScript
{
delivery: {
"t-shieam-15853": {
"state": 1,
"status": "processing",
"order": "6"
}
}
}
{
delivery: {
"t-shieam-15853": {
"state": 1,
"status": "processing",
"order": "6"
}
}
}

400|Bad Request

curl
JavaScript
{
message: "Bad Request",
payload: { }
}
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

curl
JavaScript
{
message: "Error while retrieving the delivery",
payload: { }
}
{
message: "Error while retrieving the delivery",
payload: { }
}

Get Delivery completed info

GET /v1/deliveries/{:id}/complete

This endpoint provides you a ser of completed information about the delivery and its tracking information

curl
JavaScript
curl -X GET \
https://api.shippify.co/v1/deliveries/t-shieam-15853/complete \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/json' \
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.shippify.co/v1/deliveries/t-shieam-15853/complete");
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXXXXX");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);

Responses

200|Success

curl
JavaScript
{
"id": "t-shieam-15853",
"route": {
"id": null
},
"recipient": {
"name": "John Doe",
"email": "john.doe@me.com",
"phonenumber": "+15902824949"
},
"pickup": {
"date": "2020-01-23T17:00:00.000Z"
},
"dropoff": {
"location": {
"address": "625 8th Ave, New York, NY 10018, USA",
"lat": -23.6028998,
"lng": -46.6762638
},
"date": "2020-01-23T18:00:00.000Z"
},
"courier": {
"info": {
"shipperId": 156343,
"shipperName": "John Perez",
"vehicleLicensePlate": "GBL-0289",
"vehicleType": "Sedan",
"vehicleModel": "Kia cerato"
},
"location": {
"lat": -23.602,
"lng": -46.676
}
},
"items": [
{
"id": "24",
"name": "Nike KO Hoodie 3.0",
"qty": 1,
"size": 3,
"fragile": false
}
],
"rating": null,
"delivery_feedback": "",
"status": 1,
"_status": "processing",
"distance": 5.5,
"company": "Shoes are us",
"referenceId": "40",
"groupId": null
}
{
"id": "t-shieam-15853",
"route": {
"id": null
},
"recipient": {
"name": "John Doe",
"email": "john.doe@me.com",
"phonenumber": "+15902824949"
},
"pickup": {
"date": "2020-01-23T17:00:00.000Z"
},
"dropoff": {
"location": {
"address": "625 8th Ave, New York, NY 10018, USA",
"lat": -23.6028998,
"lng": -46.6762638
},
"date": "2020-01-23T18:00:00.000Z"
},
"courier": {
"info": {
"shipperId": 156343,
"shipperName": "John Perez",
"vehicleLicensePlate": "GBL-0289",
"vehicleType": "Sedan",
"vehicleModel": "Kia cerato"
},
"location": {
"lat": -23.602,
"lng": -46.676
}
},
"items": [
{
"id": "24",
"name": "Nike KO Hoodie 3.0",
"qty": 1,
"size": 3,
"fragile": false
}
],
"rating": null,
"delivery_feedback": "",
"status": 1,
"_status": "processing",
"distance": 5.5,
"company": "Shoes are us",
"referenceId": "40",
"groupId": null
}

400|Bad Request

curl
JavaScript
{
message: "Bad Request",
payload: { }
}
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

curl
JavaScript
{
message: "Error while retrieving the delivery",
payload: { }
}
{
message: "Error while retrieving the delivery",
payload: { }
}

Get pdf labels for list of deliveries

GET /v1/deliveries/{:ids}/labels

Description

This endpoint is thought if your store needs to print an sticker when dispatching a delivery. The response of this delivery contains a Content-type of application/pdf.

curl
JavaScript
curl -X GET \
https://api.shippify.co/v1/deliveries/t-shieam-15853/labels \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/json' \
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.shippify.co/v1/deliveries/t-shieam-15853/labels");
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXXXXX");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);

Responses

200|Success

curl
JavaScript
200 OK
Content-Type: application/pdf
------------------------------------------------
id => Unique identifier for Shippify delivery
route => Unique identifier for Shippify route
deliver to => Recipient name
telephone => Recipient telephone
product => Package name
order => Order number from your integrated system
address => Recipient address
notes => Recipient address additional information
QR code => QR code with the Shippify delivery id
200 OK
Content-Type: application/pdf
------------------------------------------------
id => Unique identifier for Shippify delivery
route => Unique identifier for Shippify route
deliver to => Recipient name
telephone => Recipient telephone
product => Package name
order => Order number from your integrated system
address => Recipient address
notes => Recipient address additional information
QR code => QR code with the Shippify delivery id

400|Bad Request

curl
JavaScript
{
message: "Bad Request",
payload: { }
}
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

curl
JavaScript
{
message: "Error while retrieving the PDF label",
payload: { }
}
{
message: "Error while retrieving the PDF label",
payload: { }
}

Get pdf labels for list of deliveries

This example gives you a hint for creating a new list of deliveries, and generate a pdf with the labels for the deliveries which were just created.

curl
JavaScript
curl -X POST \
https://api.shippify.co/v1/deliveries/ \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/json' \
-d '
{
deliveries: [
{
pickup: {
contact: {
name: "Johnny Bravo",
email: "johnny@bravo.co"
},
location: {
address: "World trade center",
instructions: "En frente al central perk",
lat: "-2.1746543",
lng: "-79.8912811"
}
},
dropoff:{
contact: {
name: "Jose Garbanzo",
email: "jose@garbanzo.co"
},
location: {
address: "Central park",
lat: "-2.115618",
lng: "-79.897605"
}
},
packages: [
{
name: "item A",
size: "m",
qty: "1"
}
]
},
{
pickup: {
contact: {
name: "Jose Garbanzo",
email: "jose@garbanzo.co"
},
location: {
address: "Central park",
lat: "-2.115618",
lng: "-79.897605"
}
},
dropoff:{
contact: {
name: "Johnny Bravo",
email: "johnny@bravo.co"
},
location: {
address: "World trade center",
instructions: "En frente al central perk",
lat: "-2.1746543",
lng: "-79.8912811"
}
},
packages: [
{
name: "item A",
size: "m",
qty: "2"
}
]
}
]
}'
curl -X GET \
https://api.shippify.co/v1/deliveries/t-shieam-15853,t-shieam-15854/labels \
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
-H 'content-type: application/pdf' \
const url = 'https://api.shippify.co/v1/deliveries/'
const payload = {
deliveries: [
{
pickup: {
contact: {
name: "Johnny Bravo",
email: "johnny@bravo.co"
},
location: {
address: "World trade center",
instructions: "En frente al central perk",
lat: "-2.1746543",
lng: "-79.8912811"
}
},
dropoff:{
contact: {
name: "Jose Garbanzo",
email: "jose@garbanzo.co"
},
location: {
address: "Central park",
lat: "-2.115618",
lng: "-79.897605"
}
},
packages: [
{
name: "item A",
size: "m",
qty: "1"
}
]
},
{
pickup: {
contact: {
name: "Jose Garbanzo",
email: "jose@garbanzo.co"
},
location: {
address: "Central park",
lat: "-2.115618",
lng: "-79.897605"
}
},
dropoff:{
contact: {
name: "Johnny Bravo",
email: "johnny@bravo.co"
},
location: {
address: "World trade center",
instructions: "En frente al central perk",
lat: "-2.1746543",
lng: "-79.8912811"
}
},
packages: [
{
name: "item A",
size: "m",
qty: "2"
}
]
}
]
}
return request.post({
url: url,
headers: {
'content-type': 'application/json',
},
auth: {
user: 'API_ID',
password: 'API_SECRET'
},
body: JSON.stringify(payload)
}, (error, response, body) => {
if(error){
return res.status(400).json({ code: 'PF', message: error });
}
if(response.statusCode != 200){
console.log(body);
return res.status(response.statusCode).json({ code: 'PF', message: 'Error message' });
}
const body_parsed = JSON.parse(body)
let deliveryIds = null;
if(body_parsed.payload.length){
const arrayDeliveryIds = body_parsed.payload.map((delivery) => {
return delivery.id;
})
deliveryIds = arrayDeliveryIds.join(",")
}
if(!deliveryIds){
return res.status(response.statusCode).json({ code: 'PF', message: body.message });
}
const url_pdf = `https://api.shippify.co/v1/deliveries/${deliveryIds}/labels`
const headers = {
'content-type': 'application/pdf'
};
return req.pipe(
request.get({
headers: headers,
url: url_pdf,
auth: {
user: 'API_ID',
password: 'API_SECRET'
}
})).pipe(res);
});

Responses

200|Success

curl
JavaScript
200 OK
Content-Type: application/pdf
------------------------------------------------
id => Unique identifier for Shippify delivery
route => Unique identifier for Shippify route
deliver to => Recipient name
telephone => Recipient telephone
product => Package name
order => Order number from your integrated system
address => Recipient address
notes => Recipient address additional information
QR code => QR code with the Shippify delivery id
200 OK
Content-Type: application/pdf
------------------------------------------------
id => Unique identifier for Shippify delivery
route => Unique identifier for Shippify route
deliver to => Recipient name
telephone => Recipient telephone
product => Package name
order => Order number from your integrated system
address => Recipient address
notes => Recipient address additional information
QR code => QR code with the Shippify delivery id

400|Bad Request

curl
JavaScript
{
message: "Bad Request",
payload: { }
}
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

curl
JavaScript
{
message: "Error while retrieving the PDF label",
payload: { }
}
{
message: "Error while retrieving the PDF label",
payload: { }
}