Deliveries

The new API v1.0 allows you to create deliveries through a unique endpoint. See also different ways you can connect our service to your internal systems.

Create a new delivery

In order to create a new delivery, you can either select a quote after requesting the available ones (check here to know more) in the time window that better fits your needs, or send a direct request to the following endpoint to create a new delivery in the next hour available. If you have a preset and arranged pricing agreed in a contract, this endpoint will calculate the price based on the rules negotiated.

POST /v1/deliveries

Special Parameters

Delivery parameters: These parameters go inside each delivery in the DELIVERIES block

  • 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)

  • metadata : Extra information associated to the delivery. This could be seen as an extra referenceId.

  • tags: Strings that will tag the delivery. (array of strings, optional)

General parameters: These parameters are at the same level as the DELIVERIES block

  • quoteId : Quote generated beforehand with prices and delivery time available. (integer, optional)

  • 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)

  • type : You can set this parameter with one of the following options: express, flex, or slot. It will create the deliveries with the type specified. (Default: slot, optional)

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

Location optional parameters: These parameters go inside the LOCATION property inside the PICKUP or DROPOFF property of a DELIVERY

  • lat : Latitude number (optional)

  • lng : Longitude number (optional)

  • warehouse : Optional. Id from the list of account warehouses. If this is supplied, you don’t need to send the address. (optional)

Request Example

Note: The following is a sample payload. You should change the data with your city locations. Otherwise, you might not be able to see the deliveries created on your account due to city permissions.

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,
"metadata": {
"extraInvoice": "INVOICE_1525909_2",
"invoiceGrouping": "GROUP_1"
},
"tags":["tag1","tag2","tag3"]
}
],
"quoteId": 123456,
"flexible": true,
"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
}
],
"metadata": {
"extraInvoice": "INVOICE_1525909_2",
"invoiceGrouping": "GROUP_1"
},
"referenceId": "INVOICE_1525909",
"cod": 100,
"tags":["tag1","tag2","tag3"]
}
],
"flexible": true ,
"groupId": "7a901210-d46f-11e7-2018-01-01"
});
// instead of "flexible: true" you can also specify a quoteID
// "quoteId": 142323
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: { }
}

Get complete delivery info

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

This endpoint provides you a complete overview of a delivery . You can request this endpoint through the `delivery_id` or any other reference declared when creating the delivery.

Reference Ids are identifiers from your system that can be attached to a Shippify delivery so you can later on fetch it through it.

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

JSON
{
"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",
"status_lang": "Procesado", // lang depends on the delivery city
"distance": 5.5,
"company": "Shoes are us",
"referenceId": "40",
"groupId": null
}

400|Bad Request

JSON
{
message: "Bad Request",
payload: { }
}

500|Internal Server error

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

Generate Secure Tracking Url

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

This endpoint let's you generate the secure tracking link with a unique token that matches the information of the recipient. A secure tracking URL with a token is needed so recipients are the only ones able to see the link in their devices.

curl -X GET \ https://api.shippify.co/v1/deliveries/token/{:id} \ -H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \ -H 'content-type: application/json' \

Responses

200|Success

JSON
{
"token": "U8HpcwfvV9Y3cqTkgRMjtk",
"url": "https://api.shippify.co/track/t-shieam-17053?token=U8HpcwfvV9Y3cqTkgRMjtk&ref=server",
"recipient": {
"name": "Kevin Caicedo",
"email": "kevinca@mailinator.com",
"phonenumber": "+1202462193"
}
}

Printable Labels

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

Description

Warehouses often print labels to paste them in every package before dispatching . You can use this endpoint to generate a PDF file with the labels from an specific delivery. The response of this endpoint 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: { }
}

How to get multiple Labels

Here you can see how we send multiple delivery ids using the same endpoint to get multiple labels at once. In the `Javascript` tab, you can see code that creates multiple deliveries and then fetches a PDF document with the labels to print.

curl
JavaScript
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: { }
}

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: { }
}