Deliveries API
Search…
Introduction
General
Introduction
Authentication
Quotes
Deliveries
Statuses
Webhooks
Interactive Delivery Tracking
Integrations
Overview
Entities to know
Entities
Upcoming
The new stuff
Powered By GitBook
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 in a JSON key-value format, associated to the delivery. This could be seen as a group of 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
  • 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)
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": "[email protected]",
"phonenumber": "+19209489292"
},
"location": {
"address": "Central Park, New York, NY, United States",
"instructions": "Central Park West, APT 10920 "
}
},
"dropoff":{
"contact": {
"name": "Mary Doe",
"email": "[email protected]",
"phonenumber": "+19209085222"
},
"location": {
"address": "200 Eastern Pkwy, Brooklyn, NY 11238, USA",
"instructions": "APT 2094",
"lat": 40.6720036,
"lng": -73.9593279
},
"dueDate": "1628632740000"
},
"packages": [
{
"id": "B01LX1BBUS",
"name": "hat snapback",
"size": "xs",
"qty": 1
},
{
"id": "B071JD8VWG",
"name": "white shoes DC",
"size": "s",
"qty": 1
}
],
"referenceId": "INVOICE_1525909",
"tags":["tag1","tag2","tag3"]
}
]
}'
var data = JSON.stringify({
"deliveries": [
{
"pickup": {
"contact": {
"name": "John Doe",
"email": "[email protected]",
"phonenumber": "+19209489292"
},
"location": {
"address": "Central Park, New York, NY, United States",
"instructions": "Central Park West, APT 10920 "
}
},
"dropoff": {
"contact": {
"name": "Mary Doe",
"email": "[email protected]",
"phonenumber": "+19209085222"
},
"location": {
"address": "200 Eastern Pkwy, Brooklyn, NY 11238, USA",
"instructions": "APT 2094",
"lat": 40.6720036,
"lng": -73.9593279
},
"dueDate": "1628632740000"
},
"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: "quot;,
distance: 4.5,
id: 't-shiinc-1523090',
price: 10.00,
cityId: 1
}
}
{
message: "Delivery created successfully",
payload: {
currencyCode: "USD",
currencySign: "quot;,
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": "r-shiinc-585818",
"order": 1,
"eta": 0
},
"recipient": {
"name": "John Doe",
"email": "[email protected]",
"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,
"instructions": "Apt B",
"originalAddress": "625 8th Ave, New York, NY 10018"
},
"date": "2020-01-23T18:00:00.000Z"
},
"courier": {
"info": {
"shipperId": 156343,
"shipperDocId": "16426741-5",
"shipperName": "John Perez",
"shipperCapacity": "x_large",
"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,
"price": 78980,
"weight": 0
}
],
"rating": null,
"delivery_feedback": "",
"status": 1,
"_status": "assigned",
"status_lang": "Asignada",
"distance": 5.5,
"company": "Shoes are us",
"referenceId": "40",
"metadata": {
"CustomCodeId": "19"
},
"groupId": null,
"lastStatusDate": "2020-01-24T09:00:00.000Z"
}
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": "[email protected]",
"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: "[email protected]"
},
location: {
address: "World trade center",
instructions: "En frente al central perk",
lat: "-2.1746543",
lng: "-79.8912811"
}
},
dropoff:{
contact: {
name: "Jose Garbanzo",
email: "[email protected]"
},
location: {
address: "Central park",
lat: "-2.115618",
lng: "-79.897605"
}
},
packages: [
{
name: "item A",
size: "m",
qty: "1"
}
]
},
{
pickup: {
contact: {
name: "Jose Garbanzo",
email: "[email protected]"
},
location: {
address: "Central park",
lat: "-2.115618",
lng: "-79.897605"
}
},
dropoff:{
contact: {
name: "Johnny Bravo",
email: "[email protected]"
},
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: { }
}

​

General - Previous
Quotes
Next - General
Statuses
Last modified 11mo ago
Copy link
Outline
Create a new delivery
Special Parameters
Get complete delivery info
Generate Secure Tracking Url
Printable Labels
How to get multiple Labels