Shipmate API Guide

Getting Started

The Shipmate API provides the key functionality required to create Consignments, retrieve Tracking Events and print Labels.

We have provided a RESTful JSON API that uses industry standard HTTP Codes to communicate responses.

API URLs:

Live URL https://api.shipmate.co.uk/
Test URL https://api-staging.shipmate.co.uk/

Authentication

Authentication with the Sender API is handled by a secret token generated within the Shipmate Web Application. These tokens provide access to your account and should not be shared or stored publicly.

You can manage these tokens from the Settings area of the Shipmate Web Application.

Authentication is handled by HTTP Basic Auth - simply provide your API Key as the username. No password is required.

Example Request:

curl https://api.shipmate.co.uk/v1/parcels/9478393029817228/events \
                -u 6e0664eee3060805b643328613b750d6:

Response Structure

Response structures from the Sender API all follow the same format, providing a message that explains the response and the data of the response.

Example Response:

{
    "message": "Consignment created successfully",
    "data": {
        [
            {
                "zpl": "CT~~CD,~CC^CT~...",
                "tracking_reference": "0198288299387",
                "parcel_reference": "80000021"
            }
        ]
    }
}

Errors and HTTP Codes

Shipmate provides relevant HTTP responses to all requests to ensure that you are able to handle them correctly. A response message is also returned with each response to provide a little more information about what happened.

A list of codes that are used can be found in the table to the right.

HTTP Codes:

200 200 - OK. Everything went as expected.
201 201 - Created. An entity was created, usually the result of a POST request.
400 400 - Bad Request. There was a problem with the request, usually within validation of a POST or PUT operation
401 401 - Unauthorised. The API key that has been supplied is not valid.
403 403 - Forbidden. You do not have the priviliges required to perform the action.
500 500 - Internal Server Error. An error has occured on the server. These should never occur, however if they do the incident will be reported directly to us and we will do our best to rectify it quickly.

Validation

Validation will be performed on any requests that attempt to create or update an object within Shipmate. If validation fails, you will receive a 400 - Bad Request HTTP code as well as an error message that displays the fields that were problematic and text descriptions of each problem.

Each field could have more than one error so the messages are returned as an array.

Example Validation Response:

{
    "message": "The given data failed to pass validation.",
    "data": {
        "consignment_reference": [
            "The consignment reference field is required."
        ],
        "to_address": [
            "The to address field is required."
        ],
        "to_address.name": [
            "The to address.name field is required."
        ],
        "to_address.line_1": [
            "The to address.line 1 field is required."
        ],
        "to_address.city": [
            "The to address.city field is required."
        ],
        "to_address.postcode": [
            "The to address.postcode field is required."
        ],
        "to_address.country": [
            "The to address.country field is required."
        ],
        "parcels": [
            "The parcels field is required."
        ]
    }
}

Versioning

API Versioning for Shipmate is managed via the request URL. The current API Version is v1.

When changes are made to the API that are not backwards compatible we will release a new numbered version of the API, however older versions will still be available for use allowing you time to migrate.




Services

The Delivery Service Object

Services represent Delivery Services that you have set up in your Shipmate Account. A Service is used when creating a Consignment to specify how it should be sent.

A Service has conditions that must be met in order to use it. Service conditions merge those conditions specified by the Carrier and yourself in the Shipmate Web Application. Explanations of each field can be seen in the table to the right.

Parameters:
Parameter Description Type
id The ID of the Service in Shipmate Integer
name The readable name of the Service String
description The readable description of the Service String
key The unique key that you set when generating the Delivery Service in the Shipmate Web Application String
carrier The Carrier that the Service belongs to String
conditions An array of conditions that must be met in order to use the Service Array

Shipmate Service Conditions Structure:

field The field to compare against, e.g. Weight, Length, Volume
operator The operator that should be used in the comparison, e.g. =, >, <=
value The value that should be compared.

Get Delivery Services

The Get Services request will return an array of Delivery Services that have been set up in your Shipmate Account and are currently available to use.

You can optionally supply an array of parcel data that will be used to filter the returned Delivery Services, ensuring that any returned are valid for your Parcel

Parameters:
Parameter Description Type
weight The weight of your parcel in grammes Integer
length The length of your parcel in centimetres Integer
depth The depth of your parcel in centimetres Integer
width The width of your parcel in centimetres Integer

Example Request:

curl https://api.shipmate.co.uk/v1/services \
                -u 6e0664eee3060805b643328613b750d6:

Example Response:

{
    "message": "Services Retrieved",
    "data": [
        {
            "id": 1,
            "name": "Packet Next Day",
            "description": "Packet Next Day (Under 900g)",
            "key": "PACKETNEXT",
            "carrier": "HERMES",
            "conditions": [
                [
                    "Weight",
                    "<",
                    "900"
                ]
            ]
        },
        {
            "id": 2,
            "name": "Parcel Next Day",
            "description": "Parcel Next Day (900g and over)",
            "key": "PARCELNEXT",
            "carrier": "HERMES",
            "conditions": [
                [
                    "Weight",
                    ">=",
                    "900"
                ]
            ]
        },
        {
            "id": 3,
            "name": "Two Day",
            "description": "Two Day Delivery",
            "key": "TWODAY",
            "carrier": "HERMES",
            "conditions": [
                [
                    "Weight",
                    "<=",
                    "15000"
                ]
            ]
        },
        {
            "id": 8,
            "name": "Parcel Link",
            "description": "Parcel Link",
            "key": "PARCELINK",
            "carrier": "PARCELINK",
            "conditions": [
                [
                    "Weight",
                    ">=",
                    "900"
                ]
            ]
        },
        {
            "id": 9,
            "name": "DPD Next Day",
            "description": "DPD Next Day",
            "key": "DPDNEXT",
            "carrier": "DPD",
            "conditions": []
        }
    ]
}



Parcel Attributes

The Parcel Attribute Object

Custom Parcel Attributes are used to supply custom information to invoke specific Routing Rules.

There are six types of attribute that can be used ranging from booleans to selecting from a list of predefined values.

Parcel Attribute Types:

Type Key Description
Numeric 1 Any numeric value can be supplied
Text 2 Any text value can be supplied
Boolean (True or False) 3 A true or false value can be supplied
Boolean (Yes or No) 4 A yes or no value can be supplied
Boolean (1 or 0) 5 A 1 or 0 value can be supplied
List 6 The supplied value must be in a supplied list

Get Parcel Attributes

The Get Parcel Attributes request will return an array of available custom parcel attributes that can be used when creating a parcel.

Parcel Attributes can be supplied as part of the Create Consignment request

Example Request:

curl -X GET \
  https://api.shipmate.co.uk/v1/attributes \

Example Response:

{
    "message": "Parcel Attributes Retrieved",
    "data": [
        {
            "id": "CUSTOM_1",
            "type": 6,
            "name": "Department",
            "values": [
                "Books",
                "Stationary"
            ]
        },
        {
            "id": "CUSTOM_2",
            "type": 5,
            "name": "Fragile",
            "values": [
                "1",
                "0"
            ]
        },
        {
            "id": "CUSTOM_3",
            "type": 2,
            "name": "Product Type",
            "values": []
        }
    ]
}



Consignments

The Consignment Object

A Consignment represents the collection of parcels that you want to send for an individual order or shipment. It contains information about the parcels, the delivery service and delivery and collection addresses.

Parameters:
Parameter Description Type
consignment_reference Your unique reference for the Consignment String
delivery_service The Shipmate ID of the Delivery Service that you generated in the Shipmate Web Application String
delivery_service_key The unique key that you set when generating the Delivery Service in the Shipmate Web Application String
to_address The Address that you want to send the Consignment to Address
parcels An array of Parcels to be sent Array of Parcels

The Parcel Object

A Parcel represents each individual item that is being sent within a Consignment and tracks data such as dimensions and value.

Parameters:
Parameter Description Type
reference Your non unique reference for the Parcel String
weight The weight of the Parcel in grammes Integer
width The width of the Parcel in centimetres Integer
length The length of the Parcel in centimetres Integer
depth The depth of the Parcel in centimetres Integer
attributes An array of Custom Parcel Attributes supplied as key value pairs. Custom Parcel Attributes can be managed in the Shipmate Web Application. Dictionary

The Address Object

An Address represents a physical address that will be used as for collection or delivery.

Parameters:
Parameter Description Type
name The name of the recipient String
company_name The company name of the address String
telephone The telephone number to contact for the address String
email The email address to contact for the address String
line_1 The first line of the address String
line_2 The second line of the address String
line_3 The third line of the address String
city The city of the address String
county The county of the address String
postcode The postcode of the address String
country The two character ISO 3166-1 country code of the address String

Create a Consignment

To get a parcel label, you must create a Consignment object which tracks the delivery address, parcel details and carrier service that the consignment should be sent with.

The service_key and service_id parameters are optional. If you do not supply either then your Routing Rules will be used to select the most appropriate delivery service. If you supply both, the service_id will be used.

Arguments:
Parameter Description Type
consignment_reference Your unique reference for the Consignment String
service_key The unique key that you set when generating the Delivery Service in the Shipmate Web Application String
service_id The Shipmate ID of the Delivery Service that you generated in the Shipmate Web Application Integer
despatch_date The date for the Consignment to be despatched (YYYY-mm-dd HH:ii:ss), defaults to current day String
to_address The Address that you want to send the Consignment to Address
collection_address Address Object for the Collection Address (Your Account Address is used if not supplied) Address
format The format of the label to be returned (ZPL, PDF, PNG), defaults to ZPL String
parcels An array of Parcels to be sent Array
delivery_instructions Delivery instructions for the Carrier (e.g. Put in porch) String
contents The contents of the Consignment (e.g. Ski Equipment) String

Example Request:

curl -H "Content-Type: application/json" -X "POST" \
-d @body.json https://api.shipmate.co.uk/v1/consignments

{
	"consignment_reference": "80000001",
	"service_key": "DPDNEXT",
	"to_address": {
		"name": "Bruce Irvine",
		"line_1": "35 Ford Street",
		"city": "Derby",
		"postcode": "DE1 1EE",
		"country": "GB"
	},
	"parcels": [
		{
			"reference": "80000001-1",
			"weight": 3000,
			"width": 20,
			"length": 10,
			"depth": 15,
			"attributes":  {
				"CUSTOM_1": "Books",
				"CUSTOM_2": 0
			}
		}
	]
}

Example Response:

{
    "message": "Consignment Created",
    "data": [
        {
            "consignment_reference": "80000001",
            "parcel_reference": "80000001-1",
            "carrier": "DPD",
            "service_name": "Parcel Next Day",
            "tracking_reference": "95008001000001",
            "created_by": "John Smith",
            "created_with": "Shipmate Web App",
            "created_at": "2017-01-01 13:00:00",
            "to_address": {
                "delivery_name": "Bruce Irvine",
                "line_1": "35 Ford Street",
                "line_2": "",
                "line_3": "",
                "city": "Derby",
                "county": "",
                "postcode": "DE1 1EE",
                "country": "GB"
            },
            "pdf": "",
            "zpl": "CT~~CD,~CC^~CT~
            "png": ""
        }
    ]
}

Cancel a Consignment

Consignments can be cancelled if they have not been manifested for collection. This means the carrier is not advised about the consignment and they will not charged you for the shipment.

Example Request:

curl -X "DELETE" https://api.shipmate.co.uk/v1/consignments/9478393029817228 \
                -u 6e0664eee3060805b643328613b750d6:

Example Response:

{
    "message": "Consignment Cancelled",
    "data": null
}



Tracking Events

The Tracking Event Object

Shipmate retrieves tracking events from each Carrier and converts them into a standard Shipmate format.

Parameters:
Parameter Description Type
code The Carrier code for the Event String
name The readable name of the Event String
description The readable description of the Event String
date The date of the Event String
type The Shipmate Tracking Event Type String

Shipmate Tracking Event Types:

LABEL_CREATED Generated on Parcel creation.
MANIFESTED Triggered by Shipmate when a Parcel has been manifested and sent to a Carrier.
COLLECTED Mapped from Carrier events - Triggered when the Consignment has been collected by the Carrier.
IN_TRANSIT Mapped from Carrier events - Triggered when any Events happen between collection and delivery.
DELIVERED Mapped from Carrier events - Triggered when a Parcel has been successfully delivered.
DELIVERY_FAILED Mapped from Carrier events - Triggered when a Parcel has had a failed delivery attempt.

Get Tracking Events

The Get Tracking Events request will return an array of Shipmate Tracking Events for the requested Parcel.

Tracking Events will be returned in date order.

Example Request:

curl https://api.shipmate.co.uk/v1/parcels/9478393029817228/events \
                -u 6e0664eee3060805b643328613b750d6:

Example Response:

{
    "message": "Tracking Events Retrieved",
    "data": [
        {
            "code": "SHIP01",
            "name": "Label Created",
            "description": "The Label has been created",
            "date": "2016-06-30 08:48:57",
            "type": "LABEL_CREATED"
        },
        {
            "code": "000001022",
            "name": "Manifested",
            "description": "Manifested for Delivery",
            "date": "2016-06-30 05:08:00",
            "type": "MANIFESTED"
        },
        {
            "code": "000001256",
            "name": "In Transit",
            "description": "Carrier Received",
            "date": "2016-06-30 06:14:00",
            "type": "IN_TRANSIT"
        },
        {
            "code": "000001403",
            "name": "Delivered",
            "description": "Delivered to Outbuilding",
            "date": "2016-06-30 13:36:00",
            "type": "DELIVERED"
        }
    ]
}



Labels

The Label Object

The label object represents a single Parcel in a Consignment.

When a label is requested it is returned in a format that provides key informatiom about the parcel as well as label data in either ZPL, PDF or PNG format.

Parameters:
Parameter Description Type
consignment_reference Your unique reference for the Consignment String
parcel_reference Your non unique reference for the Parcel String
carrier The Carrier that is being used to send the Parcel String
service_name The name of the Carrier Service the Parcel is being sent with String
tracking_reference The tracking reference of the Parcel String
created_by The name of the User that generated the label String
created_with The application used to generate the label String
created_at The date that the label was created String
to_address The Address that you want to send the Consignment to Address
pdf Base 64 encoded label PDF String
zpl ZPL label String
png Base 64 encoded label PNG String

Get Label

The Get Label request will return a label in either PDF, ZPL or PNG format along with both Consignment and Parcel data.

Arguments:
Parameter Description Type
format The format that the label should be returned in. String

Example Request:

curl https://api.shipmate.co.uk/v1/parcels/9478393029817228/label \
                -u 6e0664eee3060805b643328613b750d6:

Example Response:

{
    "message": "Label retrieved",
    "data": [
        {
            "consignment_reference": "81200000",
            "parcel_reference": "81200000-1",
            "carrier": "PARCELINK",
            "service_name": "Next Day Delivery",
            "tracking_reference": "JD0002256776505380",
            "created_by": "John Smith",
            "created_with": "Shipmate Web App",
            "created_at": "2017-01-01 13:00:00",
            "to_address": {
                "delivery_name": "Bruce Irvine",
                "line_1": "38 Ford Street",
                "line_2": "",
                "line_3": "",
                "city": "Derby",
                "county": "",
                "postcode": "DE1 1EE",
                "country": "GB"
            },
            "pdf": "",
            "zpl": "CT~~CD,~CC^~CT~\...",
            "png": ""
        }
    ]
}

Print Label

The Print Label request will send a print request to a connected Printer using Shipmate's WebPrint technology.

An error will not be returned if there is not a printer to send the request to.

Example Request:

curl -X "PUT" https://api.shipmate.co.uk/v1/parcels/9478393029817228/print \
                -u 6e0664eee3060805b643328613b750d6:

Example Response:

{
    "message": "Label sent",
    "data": {
        "consignment_reference": "81200000",
        "parcel_reference": "81200000-1",
        "carrier": "PARCELINK",
        "service_name": "Next Day Delivery",
        "tracking_reference": "JD0002256776505380",
        "created_by": "John Smith",
        "created_with": "Shipmate Web App",
        "created_at": "2017-01-01 13:00:00",
        "to_address": {
            "delivery_name": "Bruce Irvine",
            "line_1": "38 Ford Street",
            "line_2": "",
            "line_3": "",
            "city": "Derby",
            "county": "",
            "postcode": "DE1 1EE",
            "country": "GB"
        },
        "pdf": "",
        "zpl": "CT~~CD,~CC^~CT~\...",
        "png": ""
    }
}