Shipmate API Guide - Version 1.0

Newer Version Available

These docs are for version 1.0 of our API. The current version is Version 1.2.

Whilst this version is still currently supported, we recommend all new integrations be done on version 1.2, as this has more features and a better user experience.

Click here to view the latest API Docs.

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.

Need a staging account? Talk to your Shipmate account manager if you already have a Shipmate account, who will be happy to set one up for you.

If you are a new customer, we will need to find out more details about your intentions for integration and can sign you up as a developer partner. Please contact sales@shipmate.co.uk or call 01332 460 888 for more information.

API URLs:

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

Request Structure

Requests should be made using JSON in the body of POST and PUT requests, with the following headers:

Accept: application/json

Content-Type: application/json

You may use simple URL-encoded parameters for GET requests, with no specific need for additional headers.

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.

Authentication

POST /tokens

Authentication with the Shipmate API is handled by a secret token obtained by authenticating using a Shipmate username and password. These tokens provide access to the user's account and should not be shared or stored publicly.

You should store the user's token in your application or session and use this in the
X-SHIPMATE-TOKEN header with all subsequent requests.

GET /tokens

To check the validity of a token, simply make a GET request to /tokens with the X-SHIPMATE-TOKEN header present in your request.

An HTTP response code of 200 will confirm your session is active.

DELETE /tokens

Tokens are persistent, however you may invalidate them by making a DELETE request to /tokens with the X-SHIPMATE-TOKEN header present in your request.

To obtain a new token, simply use the POST method again.

There are no limits to the number of active tokens each user may have. This allows you to run multiple instances of your application, or allow the same user to access different aspects of the application at the same time. For instance, the same user may be logged into the Shipmate Web Portal and Shipmate Desktop App, alongside your application at the same time.

Example Request:

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

{
    "username" : "test@shipmate.co.uk",
    "password" : "myShipmatePassword"
}

'

Example Response:

{
    "message": "Login Successful",
    "data": {
        "token": "3674eb125fe777d8c152fe52f35e78f2",
        "user": {
            "id": 123,
            "user_type": "C",
            "first_name": "Joe",
            "last_name": "Bloggs",
            "email": "test@shipmate.co.uk",
            "account_name": "Shipmate Test",
            "sender_id": "321"
        }
    }
}



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
carrier The Carrier that the Service belongs to String
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
price The price of the delivery based on cost metrics you have configured (format "0.00") 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

GET /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 Response:

{
    "message": "Services Retrieved",
    "data": [
        {
            "id": 1,
            "name": "Packet Next Day",
            "description": "Packet Next Day (Under 900g)",
            "key": "PACKETNEXT",
            "carrier": "EVRI",
            "conditions": [
                [
                    "Weight",
                    "<",
                    "900"
                ]
            ]
        },
        {
            "id": 2,
            "name": "Parcel Next Day",
            "description": "Parcel Next Day (900g and over)",
            "key": "PARCELNEXT",
            "carrier": "EVRI",
            "conditions": [
                [
                    "Weight",
                    ">=",
                    "900"
                ]
            ]
        },
        {
            "id": 3,
            "name": "Two Day",
            "description": "Two Day Delivery",
            "key": "TWODAY",
            "carrier": "EVRI",
            "conditions": [
                [
                    "Weight",
                    "<=",
                    "15000"
                ]
            ]
        },
        {
            "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.

Along with Custom Parcel Attributes, Shipmate also provides a number of attributes out of the box that are used to select services based on criteria such as Delivery Service and whether the package contains Hazardous materials.

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

Built-in Parcel Attribute:

Key Values Description
Fragile 1 or 0 States that the parcel contains fragile items
Hazardous 1 or 0 States that the parcel contains hazardous items
Perishable 1 or 0 States that the parcel contains perishable items
Aerosole 1 or 0 States that the parcel contains aerosoles
Liquid 1 or 0 States that the parcel contains liquids
DeliveryService 1, 2, 3 or 5 States the required delivery service (days until delivery is required) for the parcel
DeliveryDay SATURDAY, SUNDAY etc States the required delivery day for the parcel
DeliverySlot 10:00, 10:30 etc States the required time slot that the parcel must be delivered

Get Parcel Attributes

GET /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 Response:

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



Packaging Options

Get Packaging Options

GET /packaging-options

The Get Packaging Options request will return your Packaging Options, along with an array of available Packaging Types that can be used when creating a consignment. You may optionally provide the key of the Packaging Type you wish to use as the packaging_type_key attribute for each parcel within your consignment.

If the allow_override option is set to true, you may provide the weight and individual parcel dimensions in your POST /consignments requests, otherwise you must supply a packaging_type_key, or the default Packaging Type dimensions will be used.

If the net_weight option is set to true, the packaging_weight of the chosen Packaging Type is added to the supplied weight of the parcel, or otherwise added to the default_weight value of the Packaging Type when the consignment is created.

All weight values are in grams and all dimension values are in cm.

Example Response:

{
    "message": "Packaging Options",
    "data": [
        "net_weight": true,
        "allow_override": true,
        "packaging_types": [
            {
                "name": "Small Box",
                "key": "BOX_SMALL",
                "default": false,
                "internal_width": null,
                "internal_height": null,
                "internal_depth": null,
                "external_width": 15,
                "external_height": 15,
                "external_depth": 8,
                "max_weight": 2000,
                "default_weight": 1200,
                "packaging_weight": 60
            },
            {
                "name": "Medium Box",
                "key": "BOX_MEDIUM",
                "default": false,
                "internal_width": null,
                "internal_height": null,
                "internal_depth": null,
                "external_width": 35,
                "external_height": 30,
                "external_depth": 25,
                "max_weight": 10000,
                "default_weight": 10000,
                "packaging_weight": 100
            },
            {
                "name": "Large Box",
                "key": "BOX_LARGE",
                "default": false,
                "internal_width": null,
                "internal_height": null,
                "internal_depth": null,
                "external_width": 50,
                "external_height": 50,
                "external_depth": 40,
                "max_weight": 20000,
                "default_weight": 20000,
                "packaging_weight": 250
            },
        ]
    ]
}



Consignments

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 Shipment String
order_reference The order reference or number given to your customer. May be added to parcel labels and does not need to be unique. String
delivery_service The Shipmate ID of the Delivery Service that you generated in the Shipmate Web Portal String
delivery_service_key The unique key that you set when generating the Delivery Service in the Shipmate Web Portal. Optional, defaults to Routing Rules. String
to_address The Address that you want to send the Shipment to Address
parcels An array of Parcels to be sent Array of Parcels

Parcel Object

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

Since the Brexit Transition Period ending, when sending parcels outside of Mainland UK, you are required to add customs details for each of the parcels you are sending. These item attributes are provided along with the delivery and dimension details to the carrier, and can also be printed on a CN22 customs declaration form, if the option is enabled in your Shipmate account.

Please note If you have configured Packaging Types on your account, you can supply a packaging_type_key instead of the individual dimension and weight values. Likewise, if you have a Default Packaging Type configured, you can omit all dimension, weight and packaging type key values.
Parameters:
Parameter Description Type
reference Your unique reference for the Parcel String
packaging_type_key If using a Packaging Type, its unique key
Optional, not required if supplying weight and dimensions or using a Default Packaging Type.
String
weight The weight of the Parcel in grammes
Required unless supplying packaging_type_key or using a Default Packaging Type.
Integer
width The width of the Parcel in centimetres
Required unless supplying packaging_type_key or using a Default Packaging Type.
Integer
length The length of the Parcel in centimetres
Required unless supplying packaging_type_key or using a Default Packaging Type.
Integer
depth The depth of the Parcel in centimetres
Required unless supplying packaging_type_key or using a Default Packaging Type.
Integer
value The value of the Parcel's contents in your account's base currency (2 d.p.) Decimal
items Parcel contents details for customs declarations.
Optional for Mainland UK Deliveries.
Array of Items
attributes An array of Custom Parcel Attributes supplied as key value pairs - for example "my_custom_field_key": "My Value"

Custom Parcel Attributes can be managed in the Shipmate Web Portal.
JSON Key/Value

Items Object

Items represent each individual item that is being sent within a Parcel and tracks data such as value and customs declaration details.

Since the Brexit Transition Period ending, when sending parcels outside of Mainland UK, you are required to add customs details for each of the parcels you are sending. These item attributes are provided along with the delivery and dimension details to the carrier, and can also be printed on a CN22 customs declaration form, if the option is enabled in your Shipmate account.

Alternatively, you may use the SKU Inventory on your Shipmate account to populate all details by conducting a SKU lookup. The SKU number must match exactly the value stored on your SKU Inventory, then all subsequent attributes are optional.

Parameters:
Parameter Description Type
sku Attempts a lookup on the SKU Inventory, populating all subsequent attributes on successful match.

Optional for Mainland UK Deliveries, or where all subsequent attributes are otherwise provided.
String
short_description A short description of the parcel contents.

Optional for Mainland UK Deliveries, or when using SKU Inventory lookup.

Overrides value held on SKU Inventory whenever provided.
String
full_description The full description of the parcel contents.

Optional for Mainland UK Deliveries, or when using SKU Inventory lookup.

Overrides value held on SKU Inventory whenever provided.
String
country_of_origin Country of origin. Full name or ISO Alpha-2 code (e.g., "United Kingdom" or "GB").

Optional for Mainland UK Deliveries, or when using SKU Inventory lookup.

Overrides value held on SKU Inventory whenever provided.
String
harmonised_code Harmonised international trade code / tariff code.

Optional for Mainland UK Deliveries, or when using SKU Inventory lookup.

Overrides value held on SKU Inventory whenever provided.
String
item_value The value of each item in your account's base currency (2 d.p.).

Optional for Mainland UK Deliveries, or when using SKU Inventory lookup.

Overrides value held on SKU Inventory whenever provided.
Decimal
item_quantity The quantity of the item in the parcel.

Optional for Mainland UK Deliveries.

Defaults to 1 when using SKU Inventory lookup, unless value provided.
Integer

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_address 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

POST /consignments

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 Shipment String
service_key The unique key that you set when generating the Delivery Service in the Shipmate Web Portal. Optional, defaults to Routing Rules. String
service_id The Shipmate ID of the Delivery Service that you generated in the Shipmate Web Portal Integer
despatch_date The date for the Shipment to be despatched (YYYY-mm-dd HH:ii:ss), defaults to current day String
to_address The Address that you want to send the Shipment 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 Shipment (e.g. Ski Equipment) String

Example Request:

curl -H "Content-Type: application/json" \
-H "X-SHIPMATE-TOKEN: 3674eb125fe777d8c152fe52f35e78f2" \
-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": "2022-10-11 13:00:00",
            "price": "8.75",
            "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

DELETE /consignments/:reference

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 charge you for the shipment. Cancelled labels still count towards your Shipmate usage for the purposes of billing.

Supply your Consignment Reference as the :reference identifier in your request.

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 Events by Consignment

GET /consignments/:reference/events

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

The returned events will be grouped by Parcel, with each Parcel response including the sender reference and the Carrier Tracking Reference of the parcel.

Tracking Events will be returned in date order.

Example Response:

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

Get Events by Parcel

GET /parcels/:reference/events

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

Tracking Events will be returned in date order.

Example Response:

{
    "message": "Tracking Events Retrieved",
    "data": [
        {
            "code": "SHIP01",
            "name": "Label Created",
            "description": "The Label has been created",
            "date": "2022-10-11 08:48:57",
            "type": "LABEL_CREATED"
        },
        {
            "code": "000001022",
            "name": "Manifested",
            "description": "Manifested for Delivery",
            "date": "2022-10-11 05:08:00",
            "type": "MANIFESTED"
        },
        {
            "code": "000001256",
            "name": "In Transit",
            "description": "Carrier Received",
            "date": "2022-10-11 06:14:00",
            "type": "IN_TRANSIT"
        },
        {
            "code": "000001403",
            "name": "Delivered",
            "description": "Delivered to Outbuilding",
            "date": "2022-10-11 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 information 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 Shipment String
parcel_reference Your 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 Shipment to Address
pdf Base 64 encoded label PDF String
zpl ZPL label String
png Base 64 encoded label PNG String

Get Label

GET /parcels/:reference/label

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

Supply the Carrier's Tracking Reference as the :reference identifier in your request.

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

Example Response:

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

Print Label

PUT /parcels/:reference/print

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

Supply the Carrier's Tracking Reference as the :reference identifier in your request.

The API assumes a successful print and does not handle print failures - an error will not be returned if there is not a printer to send the request to.

Users should check any error messages on the Shipmate Desktop Application or their printer for onward troubleshooting.

Example Response:

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



Webhooks

Using Webhooks

Webhooks are outbound requests made by Shipmate when certain events have triggered inside the platform, such as tracking events or when a shipment is cancelled.

In contrast to APIs, where the 3rd Party is responsible for making requests, with Webhooks, Shipmate initiates a POST request to your chosen URL upon the event triggering in the application.

This saves making multiple requests to check the status of a shipment for example, and permits a more real-time interaction between systems.

Webhooks System Architecture Diagram

Webhook Events

Shipmate can trigger a webhook for any of the following events:

  • SHIPMENT_CREATED – Shipment Created
  • SHIPMENT_CANCELLED – Shipment Cancelled
  • TRACKING_UPDATED – Tracking Status updated (all events)
  • TRACKING_COLLECTED – Tracking Status updates to Collected
  • TRACKING_IN_TRANSIT – Tracking Status updates to In Transit
  • TRACKING_OUT_FOR_DELIVERY – Tracking Status updates to Out for Delivery
  • TRACKING_DELIVERED – Tracking Status updates to Delivered
  • TRACKING_DELIVERY_FAILED – Tracking Status updates to Delivery Failed

Configuring Webhooks

To set up a new webhook, choose the Webhooks option from the Advanced section of the Settings area on the Shipmate web portal, located at the bottom of the Settings page.

Click the New Webhook button to start creating your new webhook. This form requires the handler URL you wish us to send requests to, the event trigger, and you may provide a name to distinguish this webhook.

Advanced options allow you to configure the data type of the payload we send – either HTTP form-encoded "raw POST", or JSON. Additionally you may configure request rates and how we should handle error conditions.

Finally you may opt to narrow down this webhook to make requests from just a particular channel integration, or otherwise leave as All Shipments to send webhooks regardless of the source.

You will then be taken to the newly created webhook's overview screen, where you can monitor recent requests, trigger a test event and also copy the auth token, which will be sent as the auth_token attribute in each of our payloads for this webhook, helping you verify the authenticity of the request's origin.

Shipmate Webhooks Settings - Step 1
Shipmate Webhooks Settings - Step 2
Shipmate Webhooks Settings - Step 3
Shipmate Webhooks Settings - Step 4

Writing Your Event Handler

You may maintain separate handler endpoints for each individual event, or write a single endpoint to handle each of the event types you wish to listen for, using the event attribute in our payload to distinguish between event types.

Your handler may accept either HTTP form-encoded "raw POST" data, or JSON, according to the selection you made when configuring your webhook.

Your handler endpoint should return an HTTP 200 success code upon processing the webhook request.

You can configure the number of retry attempts Shipmate will make in case of a failed request, and we have a back-off policy enabled to spread out the time between failed requests, taking into consideration moderately lengthy downtimes.

Your webhook may be paused automatically if we receive multiple error responses or are unable to reach your server, to minimise spurious requests originating from our servers. You may reinstate paused webhooks at any time from the Settings area of the web portal.

Payload Structure (Tracking)

Tracking events are sent on a per-parcel basis. This means you may receive several similar webhooks for multiple parcels in the same shipment, providing they all progress through the carrier network at the same pace.

Parameters:
Parameter Description Type
auth_token The Webhook authentication token String
request_token Request token / idempotency token String
event Webhook event name e.g., TRACKING_DELIVERED String
shipment_reference Order number or Shipment reference String
parcel_reference Parcel reference String
source Channel key e.g., shopify_store_1 String
order_reference Order number String
carrier Carrier name e.g., DPD String
carrier_account Carrier integration key e.g., dpd_account_1 String
tracking_number Carrier tracking number String
tracking_event_code Tracking event code (from Carrier) String
tracking_event_type Tracking event stage (e.g., Collected) String
tracking_event_name Tracking event name (from Carrier) String
tracking_event_description Full event narrative String
tracking_event_time Timestamp of tracking event String
tracking_url Shipmate / co-branded tracking URL String
tracking_url_carrier Carrier tracking URL String

Payload Structure (Created and Cancelled)

Creation and Cancellation events are sent on a shipment / consignment basis. This includes all parcels within the shipment, so this payload has a slightly different structure listing out the constituent parcel references and tracking references in arrays.

Parameters:
Parameter Description Type
auth_token The Webhook authentication token String
request_token Request token / idempotency token String
event Webhook event name i.e., SHIPMENT_CANCELLED String
shipment_reference Order number or Shipment reference String
parcel_references Array of Parcel references String
source Channel key e.g., shopify_store_1 String
order_reference Order number String
carrier Carrier name e.g., DPD String
carrier_account Carrier integration key e.g., dpd_account_1 String
tracking_numbers Array of Carrier tracking numbers String

Testing a Webhook

You may trigger test events as you develop and test your implementation. Simply navigate to the webhook you wish to test, from Settings > Advanced > Webhooks, then click the Test Event button.

You are able to edit Shipment, Order and Parcel reference values that we send in the payload of the test event, to assist you with your testing and reconciling data across systems. Other values are fixed and should be treated as an example.

You can monitor the response we receive from your server by clicking the refresh button in the top-right of the event log table.

Developing locally? You may wish to use a service such as ngrok to provide an internet-connected path to your development environment.
Shipmate Webhooks - Testing a Webhook

Zapier Example

Zapier is a popular platform used to link systems together with minimal technical expertise or developer assistance being required. As such it is frequently used with webhooks to update one system when certain events are triggered in another.

To listen for events being triggered from Shipmate, set up a new Zap using the Webhooks by Zapier app.

From the three Event options offered, select the Catch Hook option. Zapier will provide you with a URL to send events to, and provide further options for linking data from the webhook and your chosen app when you test your event.

Webhooks by Zapier is a premium Zapier app and will require a paid account. Please refer to Zapier's on-screen instructions, documentation and support for further guidance and support using their product.
Webhooks Zapier Integration Example - 1
Webhooks Zapier Integration Example - 2
Webhooks Zapier Integration Example - 3



Further Information

Version History

Version 1.0.5 - October 2022

Updates include:

  • SKU Inventory lookup for international shipments
  • Webhooks
  • Other general updates and clarifications

Version 1.0.4 - February 2021

Updates include:

  • Parcels now support multiple items for customs declarations
  • Other general updates and clarifications

Version 1.0.3 - December 2020

Updates include:

  • Additional Customs Declaration fields in preparation for Brexit
  • Other general updates and clarifications

Version 1.0.2 - September 2020

Updates include:

  • Get Packaging Options and Packaging Types
  • Other general updates and clarifications

Version 1.0.1 - May 2020

Updates include:

  • Details of International Parcel Attributes
  • Details of Packaging Types
  • Other general updates and clarifications

Version 1.0.0 - July 2017

Initial API documentation