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 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)
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 -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);
200|Success
{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
{message: "Bad Request",payload: { }}
{message: "Bad Request",payload: { }}
500|Internal Server error
{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 -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
{"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
{message: "Bad Request",payload: { }}
500|Internal Server error
{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": "kevinca@mailinator.com","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 -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
200 OKContent-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 OKContent-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
{message: "Bad Request",payload: { }}
{message: "Bad Request",payload: { }}
500|Internal Server error
{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 -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);});
200|Success
200 OKContent-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 OKContent-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
{message: "Bad Request",payload: { }}
{message: "Bad Request",payload: { }}
500|Internal Server error
{message: "Error while retrieving the PDF label",payload: { }}
{message: "Error while retrieving the PDF label",payload: { }}
POST /v1/deliveries/{:id}/cancel
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);
200|Success
{message: "Delivery successfully canceled"}
{message: "Delivery successfully canceled"}
400|Bad Request
{message: "Bad Request",payload: { }}
{message: "Bad Request",payload: { }}
500|Internal Server error
{message: "Error while canceling the delivery",payload: { }}
{message: "Error while canceling the delivery",payload: { }}