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.
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
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)
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);
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 /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);
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: { }
}
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' \
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"
}
}
GET /v1/deliveries/{:ids}/labels
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);
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: { }
}
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);
});
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: { }
}
Last modified 1yr ago