Deliveries

Deliveries API
Search…
Introduction
General
Interactive Delivery Tracking
Integrations
Overview
Entities to know
Entities
Upcoming
The new stuff
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.
1
POST /v1/deliveries
Copied!
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
1
curl -X POST \
2
  https://api.shippify.co/v1/deliveries/ \
3
  -H 'authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXX' \
4
  -H 'content-type: application/json' \
5
  -d '{
6
        "deliveries": [
7
        {
8
            "pickup": {
9
                "contact": {
10
                    "name": "John Doe", 
11
                    "email": "[email protected]",
12
                    "phonenumber": "+19209489292"
13
                },
14
                "location": {
15
                    "address": "Central Park, New York, NY, United States",
16
                    "instructions": "Central Park West, APT 10920 "
17
                }
18
            },
19
            "dropoff":{
20
                "contact": {
21
                    "name": "Mary Doe", 
22
                    "email": "[email protected]",
23
                    "phonenumber": "+19209085222"
24
                },
25
                "location": {
26
                    "address": "200 Eastern Pkwy, Brooklyn, NY 11238, USA",
27
                    "instructions": "APT 2094",
28
                    "lat": 40.6720036,
29
                    "lng": -73.9593279
30
                },
31
                "dueDate": "1628632740000"
32
            },
33
            "packages": [
34
                {
35
                    "id": "B01LX1BBUS",
36
                    "name": "hat snapback",
37
                    "size": "xs",
38
                    "qty": 1
39
                },
40
                {
41
                    "id": "B071JD8VWG",
42
                    "name": "white shoes DC",
43
                    "size": "s",
44
                    "qty": 1
45
                }
46
                ],
47
            "referenceId": "INVOICE_1525909",
48
            "tags":["tag1","tag2","tag3"]
49
        }
50
    ]
51
}'
Copied!
1
var data = JSON.stringify({
2
  "deliveries": [
3
    {
4
      "pickup": {
5
        "contact": {
6
          "name": "John Doe",
7
          "email": "[email protected]",
8
          "phonenumber": "+19209489292"
9
        },
10
        "location": {
11
          "address": "Central Park, New York, NY, United States",
12
          "instructions": "Central Park West, APT 10920 "
13
        }
14
      },
15
      "dropoff": {
16
        "contact": {
17
          "name": "Mary Doe",
18
          "email": "[email protected]",
19
          "phonenumber": "+19209085222"
20
        },
21
        "location": {
22
          "address": "200 Eastern Pkwy, Brooklyn, NY 11238, USA",
23
          "instructions": "APT 2094",
24
          "lat": 40.6720036,
25
          "lng": -73.9593279
26
        },
27
        "dueDate": "1628632740000"
28
      },
29
      "packages": [
30
        {
31
          "id": "B01LX1BBUS",
32
          "name": "paperwork1",
33
          "size": "xs",
34
          "qty": 1
35
        },
36
        {
37
          "id": "B071JD8VWG",
38
          "name": "paperwork2",
39
          "size": "xs",
40
          "qty": 1
41
        }
42
      ],
43
      "metadata": {
44
        "extraInvoice": "INVOICE_1525909_2",
45
        "invoiceGrouping": "GROUP_1"
46
      },
47
      "referenceId": "INVOICE_1525909",
48
      "cod": 100,
49
      "tags":["tag1","tag2","tag3"]
50
    }
51
  ],
52
  "flexible": true , 
53
  "groupId": "7a901210-d46f-11e7-2018-01-01"
54
​
55
});
56
​
57
// instead of "flexible: true" you can also specify a quoteID
58
//  "quoteId": 142323 
59
​
60
var xhr = new XMLHttpRequest();
61
xhr.withCredentials = true;
62
​
63
xhr.addEventListener("readystatechange", function () {
64
  if (this.readyState === 4) {
65
    console.log(this.responseText);
66
  }
67
});
68
​
69
xhr.open("POST", "https://api.shippify.co/v1/deliveries/");
70
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXX");
71
xhr.setRequestHeader("content-type", "application/json");
72
​
73
xhr.send(data);
Copied!
Responses
200|Success
curl
JavaScript
1
{
2
  message: "Delivery created successfully",
3
  payload: {
4
    currencyCode: "USD",
5
    currencySign: "quot;,
6
    distance: 4.5,
7
    id: 't-shiinc-1523090',
8
    price: 10.00,
9
    cityId: 1
10
  }
11
}
Copied!
1
{
2
  message: "Delivery created successfully",
3
  payload: {
4
    currencyCode: "USD",
5
    currencySign: "quot;,
6
    distance: 4.5,
7
    id: 't-shiinc-1523090',
8
    price: 10.00,
9
    cityId: 1
10
  }
11
}
Copied!
400|Bad Request
curl
JavaScript
1
{
2
  message: "Bad Request",
3
  payload: { }
4
}
Copied!
1
{
2
  message: "Bad Request",
3
  payload: { }
4
}
Copied!
500|Internal Server error
curl
JavaScript
1
{
2
message: "Error while retrieving the quote",
3
payload: { }
4
}
Copied!
1
{
2
  message: "Error while retrieving the quote",
3
  payload: { }
4
}
Copied!
Get complete delivery info
1
GET /v1/deliveries/{:id}/complete
Copied!
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
1
  curl -X GET \
2
  https://api.shippify.co/v1/deliveries/t-shieam-15853/complete \
3
  -H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
4
  -H 'content-type: application/json' \
Copied!
1
  var data = null;
2
​
3
var xhr = new XMLHttpRequest();
4
xhr.withCredentials = true;
5
​
6
xhr.addEventListener("readystatechange", function () {
7
  if (this.readyState === 4) {
8
    console.log(this.responseText);
9
  }
10
});
11
​
12
xhr.open("GET", "https://api.shippify.co/v1/deliveries/t-shieam-15853/complete");
13
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXXXXX");
14
xhr.setRequestHeader("content-type", "application/json");
15
​
16
xhr.send(data);
Copied!
Responses
200|Success
JSON
1
{
2
    "id": "t-shieam-15853",
3
    "route": {
4
        "id": "r-shiinc-585818",
5
        "order": 1,
6
        "eta": 0
7
    },
8
    "recipient": {
9
        "name": "John Doe",
10
        "email": "[email protected]",
11
        "phonenumber": "+15902824949"
12
    },
13
    "pickup": {
14
        "date": "2020-01-23T17:00:00.000Z"
15
    },
16
    "dropoff": {
17
        "location": {
18
            "address": "625 8th Ave, New York, NY 10018, USA",
19
            "lat": -23.6028998,
20
            "lng": -46.6762638,
21
            "instructions": "Apt B",
22
            "originalAddress": "625 8th Ave, New York, NY 10018"
23
        },
24
        "date": "2020-01-23T18:00:00.000Z"
25
    },
26
    "courier": {
27
        "info": {
28
            "shipperId": 156343,
29
            "shipperDocId": "16426741-5",
30
            "shipperName": "John Perez",
31
            "shipperCapacity": "x_large",
32
            "vehicleLicensePlate": "GBL-0289",
33
            "vehicleType": "Sedan",
34
            "vehicleModel": "Kia cerato"
35
        },
36
        "location": {
37
            "lat": -23.602,
38
            "lng": -46.676
39
        }
40
    },
41
    "items": [
42
        {
43
            "id": "24",
44
            "name": "Nike KO Hoodie 3.0",
45
            "qty": 1,
46
            "size": 3,
47
            "fragile": false,
48
            "price": 78980,
49
            "weight": 0
50
        }
51
    ],
52
    "rating": null,
53
    "delivery_feedback": "",
54
    "status": 1,
55
    "_status": "assigned",
56
    "status_lang": "Asignada",
57
    "distance": 5.5,
58
    "company": "Shoes are us",
59
    "referenceId": "40",
60
    "metadata": {
61
        "CustomCodeId": "19"
62
    },
63
    "groupId": null,
64
    "lastStatusDate": "2020-01-24T09:00:00.000Z"
65
}
Copied!
400|Bad Request
JSON
1
{
2
  message: "Bad Request",
3
  payload: { }
4
}
Copied!
500|Internal Server error
JavaScript
1
{
2
  message: "Error while retrieving the delivery",
3
  payload: { }
4
}
Copied!
Generate Secure Tracking Url
1
GET /v1/deliveries/token/{:id}
Copied!
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.
1
curl -X GET \  https://api.shippify.co/v1/deliveries/token/{:id} \  -H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \  -H 'content-type: application/json' \
Copied!
Responses
200|Success
JSON
1
{
2
    "token": "U8HpcwfvV9Y3cqTkgRMjtk",
3
    "url": "https://api.shippify.co/track/t-shieam-17053?token=U8HpcwfvV9Y3cqTkgRMjtk&ref=server",
4
    "recipient": {
5
        "name": "Kevin Caicedo",
6
        "email": "[email protected]",
7
        "phonenumber": "+1202462193"
8
    }
9
}
Copied!
Printable Labels
1
GET /v1/deliveries/{:ids}/labels
Copied!
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
1
curl -X GET \
2
https://api.shippify.co/v1/deliveries/t-shieam-15853/labels \
3
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
4
-H 'content-type: application/json' \
Copied!
1
var data = null;
2
​
3
var xhr = new XMLHttpRequest();
4
xhr.withCredentials = true;
5
​
6
xhr.addEventListener("readystatechange", function () {
7
if (this.readyState === 4) {
8
console.log(this.responseText);
9
}
10
});
11
​
12
xhr.open("GET", "https://api.shippify.co/v1/deliveries/t-shieam-15853/labels");
13
xhr.setRequestHeader("authorization", "Basic XXXXXXXXXXXXXXXXXXXXXXX");
14
xhr.setRequestHeader("content-type", "application/json");
15
​
16
xhr.send(data);
Copied!
Responses
200|Success
curl
JavaScript
1
200 OK
2
Content-Type: application/pdf
3
​
4
------------------------------------------------
5
​
6
id => Unique identifier for Shippify delivery
7
​
8
route => Unique identifier for Shippify route
9
​
10
deliver to => Recipient name
11
​
12
telephone => Recipient telephone
13
​
14
product => Package name
15
​
16
order => Order number from your integrated system
17
​
18
address => Recipient address
19
​
20
notes => Recipient address additional information
21
​
22
QR code => QR code with the Shippify delivery id
Copied!
1
200 OK
2
Content-Type: application/pdf
3
​
4
------------------------------------------------
5
​
6
id => Unique identifier for Shippify delivery
7
​
8
route => Unique identifier for Shippify route
9
​
10
deliver to => Recipient name
11
​
12
telephone => Recipient telephone
13
​
14
product => Package name
15
​
16
order => Order number from your integrated system
17
​
18
address => Recipient address
19
​
20
notes => Recipient address additional information
21
​
22
QR code => QR code with the Shippify delivery id
Copied!
400|Bad Request
curl
JavaScript
1
{
2
  message: "Bad Request",
3
  payload: { }
4
}
Copied!
1
{
2
  message: "Bad Request",
3
  payload: { }
4
}
Copied!
500|Internal Server error
curl
JavaScript
1
{
2
message: "Error while retrieving the PDF label",
3
payload: { }
4
}
Copied!
1
{
2
  message: "Error while retrieving the PDF label",
3
  payload: { }
4
}
Copied!
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
1
curl -X GET \
2
https://api.shippify.co/v1/deliveries/t-shieam-15853,t-shieam-15854/labels \
3
-H 'authorization: Basic XXXXXXXXXXXXXXXXXXX' \
4
-H 'content-type: application/pdf' \
Copied!
1
  const url = 'https://api.shippify.co/v1/deliveries/'
2
  const payload = {
3
    deliveries: [
4
    {
5
      pickup: {
6
        contact: {
7
          name: "Johnny Bravo",
8
          email: "[email protected]"
9
        },
10
        location: {
11
          address: "World trade center",
12
          instructions: "En frente al central perk",
13
          lat: "-2.1746543",
14
          lng: "-79.8912811"
15
        }
16
      },
17
      dropoff:{
18
        contact: {
19
          name: "Jose Garbanzo",
20
          email: "[email protected]"
21
        },
22
        location: {
23
          address: "Central park",
24
          lat: "-2.115618",
25
          lng: "-79.897605"
26
        }
27
      },
28
      packages: [
29
        {
30
          name: "item A",
31
          size: "m",
32
          qty: "1"
33
        }
34
      ]
35
    },
36
    {
37
      pickup: {
38
        contact: {
39
          name: "Jose Garbanzo",
40
          email: "[email protected]"
41
        },
42
        location: {
43
          address: "Central park",
44
          lat: "-2.115618",
45
          lng: "-79.897605"
46
        }
47
      },
48
      dropoff:{
49
        contact: {
50
          name: "Johnny Bravo",
51
          email: "[email protected]"
52
        },
53
        location: {
54
          address: "World trade center",
55
          instructions: "En frente al central perk",
56
          lat: "-2.1746543",
57
          lng: "-79.8912811"
58
        }
59
      },
60
      packages: [
61
        {
62
          name: "item A",
63
          size: "m",
64
          qty: "2"
65
        }
66
      ]
67
    }
68
    ]
69
  }
70
  return request.post({
71
    url: url,
72
    headers: {
73
      'content-type': 'application/json',
74
    },
75
    auth: {
76
      user: 'API_ID',
77
      password: 'API_SECRET'
78
    },
79
    body: JSON.stringify(payload)
80
  }, (error, response, body) => {
81
    if(error){
82
      return res.status(400).json({ code: 'PF', message: error });
83
    }
84
    if(response.statusCode != 200){
85
      console.log(body);
86
      return res.status(response.statusCode).json({ code: 'PF', message: 'Error message' });
87
    }
88
​
89
    const body_parsed = JSON.parse(body)
90
    let deliveryIds = null;
91
    if(body_parsed.payload.length){
92
      const arrayDeliveryIds = body_parsed.payload.map((delivery) => {
93
        return delivery.id;
94
      })
95
      deliveryIds = arrayDeliveryIds.join(",")
96
    }
97
​
98
    if(!deliveryIds){
99
      return res.status(response.statusCode).json({ code: 'PF', message: body.message });
100
    }
101
    const url_pdf = `https://api.shippify.co/v1/deliveries/${deliveryIds}/labels`
102
​
103
    const headers = {
104
      'content-type': 'application/pdf'
105
    };
106
    return req.pipe(
107
      request.get({
108
        headers: headers,
109
        url: url_pdf,
110
        auth: {
111
          user: 'API_ID',
112
          password: 'API_SECRET'
113
        }
114
      })).pipe(res);
115
  });
Copied!
Responses
200|Success
curl
JavaScript
1
200 OK
2
Content-Type: application/pdf
3
​
4
------------------------------------------------
5
​
6
id => Unique identifier for Shippify delivery
7
​
8
route => Unique identifier for Shippify route
9
​
10
deliver to => Recipient name
11
​
12
telephone => Recipient telephone
13
​
14
product => Package name
15
​
16
order => Order number from your integrated system
17
​
18
address => Recipient address
19
​
20
notes => Recipient address additional information
21
​
22
QR code => QR code with the Shippify delivery id
Copied!
1
200 OK
2
Content-Type: application/pdf
3
​
4
------------------------------------------------
5
​
6
id => Unique identifier for Shippify delivery
7
​
8
route => Unique identifier for Shippify route
9
​
10
deliver to => Recipient name
11
​
12
telephone => Recipient telephone
13
​
14
product => Package name
15
​
16
order => Order number from your integrated system
17
​
18
address => Recipient address
19
​
20
notes => Recipient address additional information
21
​
22
QR code => QR code with the Shippify delivery id
Copied!
400|Bad Request
curl
JavaScript
1
{
2
message: "Bad Request",
3
payload: { }
4
}
Copied!
1
{
2
message: "Bad Request",
3
payload: { }
4
}
Copied!
500|Internal Server error
curl
JavaScript
1
{
2
message: "Error while retrieving the PDF label",
3
payload: { }
4
}
Copied!
1
{
2
message: "Error while retrieving the PDF label",
3
payload: { }
4
}
Copied!
​