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:

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 Shipmate 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:

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.1.

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.

Registering Your Application

Before you can make API requests, you must first register your application to obtain an API Key.

This can be done by navigating to Settings, then API Keys. Then click the Register API Key button.

On the Register API Key form, enter a name for your application, then select from the list of application types - either Channel, Source or General App:

• Channel should be used for single-channel sources such as an eCommerce platform.
• Source should be used for multi-channel inputs such as Order Management Systems or Warehouse Management Systems.
• General App can be used for anything else that requires API access.

Once you are happy with your selections, click the Save button. This will generate a unique API key for your application.

Click the Reveal Key button to view and copy your Shipmate API key.

You should store your API key in your application and use this in the
X-SHIPMATE-API-KEY header with all requests you make to the API.

Setting an Application Icon

Icons can be uploaded to applications, providing familiarity for people using your application across Shipmate.

Once you have created your API Key, simply click the empty image icon to begin the upload process. Choose an image from your computer, position it correctly using the on-screen selection tool, then click Upload.

Your icon will then be shown on shipments created using your application, on the individual shipment page. We intend to use app icons across further areas of the Shipmate platform in the coming months.

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.

Example Request:

curl -H "Content-Type: application/json" \
-H "X-SHIPMATE-API-KEY: sm_test_12345abcde-1234-5678-90ab-abcdef0123456" \
-X "POST" \
https://api.shipmate.co.uk/v1.1/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"
        }
    }
}

Location Object

These represent the Locations you have set up in your Shipmate account.

A Location is used when creating a Consignment to set the address and contact details of the source or collection address of the delivery, with these details typically appearing in the sender section of shipping labels when supported by the carrier.

If a Location is not specified, the account's Default Location is used for the Consignment.

Parameters:

Parameter	Description	Type
uuid	Unique system identifier	String
code	Location code e.g., HQ	String
name	Location name e.g., Headquarters	String
type	Type of Location e.g., Store or Warehouse	String
telephone	Telephone number for the Location	String
email	Email address for the Location	String
address_name	Company or FAO name for Location	String
address_line_1	Address line 1 of Location	String
address_line_2	Address line 2 of Location	String
address_line_3	Address line 3 of Location	String
address_town_city	Town or city of Location	String
address_county	County of Location	String
address_country	Country of Location	Country
address_post_zip_code	Postcode of Location	String
default	Whether this is the account's default Location	Boolean
created_at	When the Location was first created on Shipmate	Datetime
updated_at	When the Location was last updated on Shipmate	Datetime

Get All Locations

GET /locations

Retrieves a list of all Locations on the Shipmate account.

Example Response:

{
    "message": "Locations",
    "data": {
        "data": [
            {
                "uuid": "bae33e4a-5996-423d-acb3-e663e42e6e34",
                "code": "DC1",
                "name": "Derby Office",
                "type": "STORE",
                "telephone": "01332 460888",
                "email": "derby@shipmate.co.uk",
                "address_name": "Shipmate Demo",
                "address_line_1": "Shipmate Demo",
                "address_line_2": "Friar Gate Studios",
                "address_line_3": null,
                "address_town_city": "Derby",
                "address_county": "Derbyshire",
                "address_country": {
                    "code": "GB",
                    "name": "United Kingdom"
                },
                "address_post_zip_code": null,
                "default": true,
                "created_at": "2021-10-21 10:25:23",
                "updated_at": "2023-02-01 11:05:50"
            },
            {
                "uuid": "6d894299-e3e6-4c4a-8b07-925d40b67f28",
                "code": "DC2",
                "name": "Manchester Office",
                "type": "OTHER",
                "telephone": "0161 883 0383",
                "email": "manchester@shipmate.co.uk",
                "address_name": "Shipmate",
                "address_line_1": "Bonded Warehouse",
                "address_line_2": "18 Lower Byrom Street",
                "address_line_3": null,
                "address_town_city": "Manchester",
                "address_county": null,
                "address_country": {
                    "code": "GB",
                    "name": "United Kingdom"
                },
                "address_post_zip_code": null,
                "default": false,
                "created_at": "2021-11-22 15:03:29",
                "updated_at": "2023-02-01 11:05:50"
            }
        ]
    }
}

Get Single Location

GET /locations/:ref

Retrieves a specific Location on the Shipmate account by :ref, which may be either the Location code or UUID.

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:

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

Built-in Parcel Attribute:

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": []
        }
    ]
}

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
            },
        ]
    ]
}

SKU Object

A SKU represents a stock keeping unit or product that you will despatch in orders.

Parameters:

Parameter	Description	Type
uuid	Unique system identifier	String
sku	SKU number used to match on your other systems	String
product_name	The name of the product	String
outer_barcode	Barcode used on the containing packaging of the product	String
inner_barcode	Barcode used on the product	String
product_code	The manufacturer's product number or code	String
description_short	A short description of the product	String
description_full	The full description of the product	String
department	Department name or code for categorisation	String
category	Category name	String
location	The Location this SKU is held at	Location
warehouse_location	Storage location code to help you locate SKU	String
tariff_code	Harmonised Code or Tariff Code for Customs Declarations	String
tariff_description	Product description for Customs Declarations	String
country_of_origin	Country of Origin for Customs Declarations	Country
manufacturer_name	Manufacturer name	String
part_number	Manufacturer part number	String
value_ex_vat	Value of SKU excluding VAT	Decimal
vat_rate	The VAT Rate of this SKU	Decimal
value_inc_vat	Value of SKU including VAT	Decimal
gross_weight	Gross weight of SKU, in grammes	Integer
net_weight	Net weight of SKU, in grammes	Integer
width	Width of SKU, in mm	Integer
length	Length of SKU, in mm	Integer
depth	Depth of SKU, in mm	Integer
hazard_codes	UN hazard codes	Array
is_stocked_item	Whether this is an item kept in stock	Boolean
in_stock	Whether this item is currently in stock	Boolean
created_at	Date and time SKU was created	Datetime
updated_at	Date and time SKU was last updated	Datetime

Create SKU

POST /skus

Adds a new SKU to the Shipmate account.

Required attributes are highlighted and starred.

Parameters:

Parameter	Description	Type
sku	SKU number used to match on your other systems	String
product_name	The name of the product	String
outer_barcode	Barcode used on the containing packaging of the product	String
inner_barcode	Barcode used on the product	String
product_code	The manufacturer's product number or code	String
description_short	A short description of the product	String
description_full	The full description of the product	String
department	Department name or code for categorisation	String
category	Category name	String
location	The Location this SKU is held at. Location code or UUID. Uses default if omitted.	String
warehouse_location	Storage location code to help you locate SKU	String
tariff_code	Harmonised Code or Tariff Code for Customs Declarations	String
tariff_description	Product description for Customs Declarations	String
country_of_origin	Country of Origin for Customs Declarations. The two character ISO 3166-1 country code, e.g., GB	String
manufacturer_name	Manufacturer name	String
part_number	Manufacturer part number	String
value_ex_vat	Value of SKU excluding VAT	Decimal
vat_rate	The VAT Rate of this SKU	Decimal
value_inc_vat	Value of SKU including VAT	Decimal
gross_weight	Gross weight of SKU, in grammes	Integer
net_weight	Net weight of SKU, in grammes	Integer
width	Width of SKU, in mm	Integer
length	Length of SKU, in mm	Integer
depth	Depth of SKU, in mm	Integer
hazard_codes	UN hazard codes	Array
is_stocked_item	Whether this is an item kept in stock	Boolean
in_stock	Whether this item is currently in stock	Boolean

Update SKU

PUT /skus/:ref

Updates a SKU on your Shipmate account by :ref, which may be either the SKU number or UUID.

Uses the same attributes as per POST /skus above. Acts like a PATCH request in that only the attributes you wish to update are necessary.

Get SKUs

GET /skus

Retrieves a paginated list of SKUs on the Shipmate account, 30 records at a time.

Example Response:

{
    "data": [
        {
            "uuid": "17db8d26-bcf0-409b-937c-9f64cf95be70",
            "sku": "TSHIRT1-XS",
            "product_name": "Shipmate Blue T-Shirt (XS)",
            ...
        },
        {
            "uuid": "265a0b15-9cb9-4322-9568-6587f30b7bc9",
            "sku": "TSHIRT1-S",
            "product_name": "Shipmate Blue T-Shirt (S)",
            ...
        },
        {
            "uuid": "19c15b14-bfac-4348-b887-03bdbe6fb081",
            "sku": "TSHIRT1-M",
            "product_name": "Shipmate Blue T-Shirt (M)",
            ...
        },
        ...
    ],
    "links": {
        "first": "https://api.shipmate.co.uk/v1.1/skus?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://api.shipmate.co.uk/v1.1/skus",
        "per_page": 30,
        "to": 6
    }
}

Get Single SKU

GET /skus/:ref

Retrieves a specific SKU on the Shipmate account by :ref, which may be either the SKU number or UUID.

User Object

The following User representation is available on the Shipmate API:

Parameters:

Parameter	Description	Type
uuid	Unique system identifier	String
title	e.g., Mr, Miss, Mrs, Mx	String
first_name	The user's first name	String
last_name	The user's last name	String
email	The user's email address	String
profile_image_url	URL to the user's profile image	String
location	The user's currently assigned Location	Location
access_level	The user's access level, one of MERCHANT_ADMIN, MERCHANT_USER, 3PL_ADMIN, 3PL_USER	String
printer_online	Returns true if the user currently has the Desktop Printer App running	Boolean

Get Users

GET /users

Retrieves a list of Users on the Shipmate account.

Example Response:

{
    "data": [
        {
            "uuid": "caf1e96a- ... -9d10781e",
            "title": "Mr",
            "first_name": "Shipmate",
            "last_name": "Demo",
            "email": "demo@shipmate.co.uk",
            "profile_image_url": "https://shipmate-user-profile-images... .png",
            "location": {
                "uuid": "bae33e4a-5996-423d-acb3-e663e42e6e34",
                "code": "DC1",
                "name": "Derby Office",
                "type": "STORE",
                "telephone": "01332 460 888",
                "email": "derby@shipmate.co.uk",
                "address_name": "Shipmate Derby Office",
                "address_line_1": "Shipmate",
                "address_line_2": "Friar Gate Studios",
                "address_line_3": null,
                "address_town_city": "Derby",
                "address_county": "Derbyshire",
                "address_country": {
                    "code": "GB",
                    "name": "United Kingdom"
                },
                "address_post_zip_code": "DE1 1EE",
                "default": true,
                "created_at": "2021-10-21 10:25:23",
                "updated_at": "2023-05-29 11:39:16"
            },
            "access_level": "MERCHANT_ADMIN",
            "printer_online": true
        },
        ...
    ]
}

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
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 Application	String
delivery_service_key	The unique key that you set when generating the Delivery Service in the Shipmate Web Application	String
location_code	Lets you state which Location you are sending this Consignment from. Optional, defaults to your Default Location.	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

Create Consignment

POST /consignments

To generate parcel labels, create a Consignment object which tracks the delivery address, parcel details and carrier service that the consignment should be sent with.

The service_key attribute is optional. If omitted, your Routing Rules will be used to select the most appropriate delivery service.

Arguments:

Parameter	Description	Type
consignment_reference	Your unique reference for the Consignment	String
service_key	Optional key to state the desired Delivery Service. Uses Shipmate Routing Rules if omitted.	String
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
location_code	Code of Location this Shipment is being despatched from. Uses default Location if omitted.	String
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

Example Request:

curl -H "Content-Type: application/json" \
-H "X-SHIPMATE-API-KEY: sm_test_12345abcde-1234-5678-90ab-abcdef0123456" \
-H "X-SHIPMATE-TOKEN: 3674eb125fe777d8c152fe52f35e78f2" \
-X "POST" \
-d @body.json \
https://api.shipmate.co.uk/v1.1/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": "2023-03-15 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 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
}

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.

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
customs_declaration	Export Purpose, if overriding defaults. Optional for Mainland UK Deliveries. Uses default Export Purpose if omitted.	Customs Declaration
attributes	An array of Custom Parcel Attributes supplied as key value pairs. Custom Parcel Attributes can be managed in the Shipmate Web Application.	Dictionary

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

Country Object

The Country object contains the following:

Parameters:

Parameter	Description	Type
code	The two character ISO 3166-1 country code, e.g., GB	String
name	The full name of the country, e.g., United Kingdom	String

Customs Declaration Object

The Customs Declaration object contains the following:

Parameters:

Parameter	Description	Type
export_purpose	Export Purpose for customs declaration	Export Purpose

Export Purpose Object

The Export Purpose object contains the following:

Parameters:

Parameter	Description	Type
gift	True if this Parcel contains a Gift	Boolean
documents	True if this Parcel contains Documents	Boolean
sale_of_goods	True if this Parcel is for Sale of Goods	Boolean
commercial_sample	True if this Parcel contains a Commercial Sample	Boolean
returned_goods	True if this Parcel contains Returned Goods	Boolean
other	Other export purpose, if not represented by one of the above options.	String

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:

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": "2023-03-16 08:48:57",
                    "type": "LABEL_CREATED"
                },
                {
                    "code": "000001022",
                    "name": "Manifested",
                    "description": "Manifested for Delivery",
                    "date": "2023-03-16 05:08:00",
                    "type": "MANIFESTED"
                },
                {
                    "code": "000001256",
                    "name": "In Transit",
                    "description": "Carrier Received",
                    "date": "2023-03-16 06:14:00",
                    "type": "IN_TRANSIT"
                },
                {
                    "code": "000001403",
                    "name": "Delivered",
                    "description": "Delivered to Outbuilding",
                    "date": "2023-03-16 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": "2023-03-16 08:48:57",
            "type": "LABEL_CREATED"
        },
        {
            "code": "000001022",
            "name": "Manifested",
            "description": "Manifested for Delivery",
            "date": "2023-03-16 05:08:00",
            "type": "MANIFESTED"
        },
        {
            "code": "000001256",
            "name": "In Transit",
            "description": "Carrier Received",
            "date": "2023-03-16 06:14:00",
            "type": "IN_TRANSIT"
        },
        {
            "code": "000001403",
            "name": "Delivered",
            "description": "Delivered to Outbuilding",
            "date": "2023-03-16 13:36:00",
            "type": "DELIVERED"
        }
    ]
}

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 Consignment	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 Consignment 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": "2023-03-15 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 Labels

PUT /shipments/:reference/print

The Print Label request will send the given Shipment's label(s) to the authenticated User's Desktop Printer App.

Supply the Shipment ID or reference, Order reference, Shipmate tracking reference or the Carrier's tracking reference as the :reference identifier in your request.

Optionally, you may supply the uuid of the User you wish to send the print request to.

Arguments:

Parameter	Description	Type
print_to_user	Optional UUID of User you wish to print to	String

Example Response:

{
    "message": "1 label sent to printer",
    "data": []
}

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.

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.

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.

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.

Version History

Version 1.1.2 - July 2023

Updates include:

• Ability to set Customs Declaration Export Purpose

Version 1.1.1 - June 2023

Updates include:

• New Get Users method
• New Print to User method

Version 1.1.0 - March 2023

Updates include:

• New API endpoint URL
• Requirement of API Key for all methods
• Ability to upload App Icon
• Locations methods
• SKU Inventory methods
• location_code attribute on POST Consignments method

Version 1.0.0 - July 2017 - Version 1.0.5 - October 2022

View version 1.0 API documentation