Deliveries

Last updated 2 months ago
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
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 and delivery time available. (integer, optional)
groupId : In case you need to group a list of deliveries, and later identify the batch created (string, optional)
metadata : Extra information associated to the delivery. This could be seen as an extra referenceId.
Request
Note: The following  is a sample payload.  You should change the data with you 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",
            "metadata": {
                "extraInvoice": "INVOICE_1525909_2",
                "invoiceGrouping": "GROUP_1"
            },
            "cod": 100,
            "tags":["tag1","tag2","tag3"]
        }
        ],
    "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: { }
}
​