Shipmate API Guide - Version 1.2

Getting Started

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

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

Need a development 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 customer or developer partner. Please contact sales@shipmate.co.uk or call +44 (0)1332 460 888 for more information.

API URLs:

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

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": "Shipment 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.
404 404 - Not Found. The resource you requested could not be found.
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": {
        "shipment_reference": [
            "The shipment 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.2.

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.

Register Shipmate API Key - Step 1
Hover
Register Shipmate API Key - Step 1
Register Shipmate API Key - Step 2
Hover
Register Shipmate API Key - Step 2
Register Shipmate API Key - Step 3
Hover
Register Shipmate API Key - Step 3
Register Shipmate API Key - Step 4

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.

We recommend icons are square in proportion with dimensions at least 400 x 400px and with a transparent background in PNG format.
Setting App Icon - Step 1
Hover
Setting Shipmate API App Icon - Step 1
Setting Shipmate API App Icon - Step - Step 2
Setting Shipmate API App Icon - Step - Step 3
Setting Shipmate API App Icon - Step - Step 4

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" \
-H "X-SHIPMATE-API-KEY: sm_test_12345abcde-1234-5678-90ab-abcdef0123456" \
-X "POST" \
https://api.shipmate.co.uk/v1.2/tokens -d '

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

'

Example Response:

{
    "message": "Login Successful",
    "data": {
        "token": "3674eb125fe777d8c152fe52f35e78f2",
        "user": {
            "id": "caf1e96a- ... -9d10781e",
            "user_type": "C",
            "first_name": "Joe",
            "last_name": "Bloggs",
            "email": "test@shipmate.co.uk",
            "account_name": "Shipmate Test",
            "merchant_id": "fdc2e13b- ... -8a12483c"
        }
    }
}



Developer Resources

Postman Collection

We have prepared a Postman Collection to help you get started developing your API integration with sample requests and examples that follow various scenarios.

You will need to configure 3x Variables in the Collection to be able to use it correctly:

Download Postman Collection

Composer Package SDK

If you are integrating Shipmate with a PHP application, we recommend using our officially supported SDK via Composer:

composer require shipmate/shipmate-php-sdk

View full details on Packagist.org...




Shipments

Create Shipment

POST /shipments

This method creates a Shipment, generating shipping labels in your desired format and also returns tracking details.

Supply JSON encoded data as per the attributes described in the Shipment object to create your Shipment.

The delivery_service_key attribute is optional. If omitted, your Routing Rules will be used to select the most appropriate Delivery Service.

The location_code attribute is optional. If omitted, the user's Default Location will be used.

The despatch_date attribute is optional. If omitted, the current date will be used.

The customs_declaration, recipient_vat_number and recipient_eori_number attributes are optional for domestic Shipments.

The format attribute is optional. Labels will be returned in ZPL (Zebra Printer Language) as a string by default, or you may opt to retrieve labels in PDF or PNG format, both of which will be returned as a base64 encoded string. If using the print_labels option, labels will be returned in the format selected by the user in the Shipmate Desktop App.

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.2/shipments

{
    "shipment_reference": "80000001",
    "delivery_service_key": "DPD_LOCAL_PARCEL_24",
    "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,
            "custom_fields":  {
                "category": "Books",
                "is_perishable": false
            }
        },
        ...
    ]
}

Example Response:

{
    "message": "Shipment Created",
    "data": [
        {
            "shipment_reference": "80000001",
            "parcel_reference": "80000001-1",
            "carrier": "DPD Local",
            "service_name": "Parcel Next Day",
            "tracking_reference": "95008001000001",
            "created_by": "John Smith",
            "created_with": "Shipmate Web App",
            "created_at": "2024-02-22 13:00:00",
            "price": "8.75",
            "estimated_delivery_date": "2024-03-01 20: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~ ... ^PQ1,0,1,Y^XZ",
            "png": ""
        }
    ]
}

Get Services for Shipment

POST /shipments/get-services

This method retrieves all suitable services for the supplied Shipment, along with delivery costs. Services are returned in ascending order of the total_price, with the cheapest available service first.

Also returns the recommended_service, which is a copy of the Delivery Service that any Routing Rules have recommended, or otherwise the cheapest service that meets the Shipment's requirements.

Use this method to display options for users to select their desired Delivery Service, or to validate a Shipment.

Supply JSON encoded data as per the attributes described in the Shipment object and the Create Shipment endpoint to retrieve Delivery Services and costings for your Shipment.

Requests made to this endpoint do not count towards your label usage allowance, and we recommended this is used with interactive user interfaces.

Example Response:

{
    "message": "Available Services Retrieved",
    "data": {
        "recommended_service":
        {
            "carrier": "DPD Local",
            "carrier_account": "DPD Local - Primary Account",
            "service_name": "Parcel 48 Hours",
            "full_service_name": "DPD Local - Primary Account - Parcel 48 Hours",
            "service_key": "DPD_LOCAL_PARCEL_48",
            "base_price": "7.20",
            "additional_parcel_price": "4.00",
            "surcharges": "0.00",
            "fuel_surcharge": "11.12",
            "total_price": "12.32",
            "estimated_delivery_date": "2024-03-02 20:00"
        },
        "services": [
            {
                "carrier": "DPD Local",
                "carrier_account": "DPD Local - Primary Account",
                "service_name": "Parcel 48 Hours",
                "full_service_name": "DPD Local - Primary Account - Parcel 48 Hours",
                "service_key": "DPD_LOCAL_PARCEL_48",
                "base_price": "7.20",
                "additional_parcel_price": "4.00",
                "surcharges": "0.00",
                "fuel_surcharge": "11.12",
                "total_price": "12.32",
                "estimated_delivery_date": "2024-03-02 20:00"
            },
            {
                "carrier": "DPD Local",
                "carrier_account": "DPD Local - Primary Account",
                "service_name": "Parcel Next Day",
                "full_service_name": "DPD Local - Primary Account - Parcel Next Day",
                "service_key": "DPD_LOCAL_PARCEL_24",
                "base_price": "8.50",
                "additional_parcel_price": "5.50",
                "surcharges": "0.00",
                "fuel_surcharge": "1.40",
                "total_price": "15.40",
                "estimated_delivery_date": "2024-03-01 20:00"
            },
            ...
        ]
    }
}

Cancel Shipment

DELETE /shipments/:ref

Shipments can be cancelled if they have not been manifested for collection. This means the carrier is not advised about the Shipment and they should not charge you for it. Cancelled labels still count towards your Shipmate usage for the purposes of billing.

Supply your Shipment Reference as the :ref identifier in your request.

Example Response:

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

Shipment Object

A Shipment 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
shipment_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_key The unique key that you set when generating the Delivery Service in the Shipmate Web Portal. Optional, defaults to Routing Rules. String
location_code Lets you state which Location you are sending this Shipment from. Optional, defaults to your Default Location. String
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
parcels An array of Parcels to be sent Array of Parcels
delivery_instructions Delivery instructions for the Carrier (e.g. Put in porch) String
custom_fields Array of Custom Fields supplied as key => value pairs - for example "my_custom_field_key": "My Value"

Custom Fields can be managed in the Shipmate Web Portal.
JSON Key/Value
customs_declaration Customs Declaration details, for international destinations, if overriding defaults Customs Declaration
recipient_vat_number The recipient's VAT number, for international destinations String
recipient_eori_number The recipient's EORI number, for international destinations String
format The format of the label to be returned (ZPL, PDF, PNG), defaults to ZPL String
print_labels Set to true to send generated label(s) to the authenticated user's Shipmate Desktop App

Default value is false.
Boolean
print_to_user Optional ID of User you wish to print to.

print_labels must be set to true when setting this attribute.
String

Parcel Object

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

If a Shipment requires a Customs Declaration, item level details need to be supplied. 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 forms or Commercial Invoices, if required.

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
customs_declaration Customs Declaration details, for international destinations, if overriding defaults. Customs Declaration
custom_fields Array of Custom Fields supplied as key => value pairs - for example "my_custom_field_key": "My Value"

Custom Fields 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.

If a Shipment requires a Customs Declaration, item level details need to be supplied. These item attributes are provided along with the delivery and dimension details to the carrier, and can also be printed on CN22 Customs Declaration forms or Commercial Invoices, if required.

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
item_line_id Used to link Items across multiple parcels.

Optional, but if value matches the item will be considered to be split across the parcels this value appears.

If used, additional validation prevents other non-matching Items appearing in the same Parcel.
String
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_weight The weight of each item in grammes.

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

Overrides value held on SKU Inventory whenever provided.
Integer
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
duty_method Whether this is DAP or DDP. Defaults to value on account.

Accepts only DAP or DDP.
String
commercial_invoice_number Defaults to Order Reference. String
insurance_value Used to populate Commercial Invoice. Defaults to 0.00. Decimal
freight_value Used to populate Commercial Invoice. Defaults to 0.00. Decimal
packing_value Used to populate Commercial Invoice. Defaults to 0.00. Decimal
handling_value Used to populate Commercial Invoice. Defaults to 0.00. Decimal
other_value Used to populate Commercial Invoice. May be a negative value for discounts. Defaults to 0.00. Decimal
currency_code Used to populate Commercial Invoice. Defaults to account value.

Accepts ISO currency code e.g., GBP, EUR.
String
export_license_number Used to populate Commercial Invoice. Optional. String
export_certificate_number Used to populate Commercial Invoice. Optional. String
other_export_comments Used to populate Commercial Invoice. Optional, accepts up to 1,000 characters. String
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



Users

User Object

The following User representation is available on the Shipmate API:

Parameters:
Parameter Description Type
id 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": [
        {
            "id": "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": {
                "id": "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
        },
        ...
    ]
}



Locations

Location Object

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

A Location is used when creating a Shipment 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 Shipment.

Parameters:
Parameter Description Type
id 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": [
            {
                "id": "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": "2024-02-01 11:05:50"
            },
            {
                "id": "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": "2024-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 ID.




Services

Delivery Service Object

Services represent Delivery Services that you have set up in your Shipmate Account. A Service is used when creating a Shipment 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 String
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": "cf578671-c9b6-4e96-b836-22dd8b9cb043",
            "name": "Packet Next Day",
            "description": "Packet Next Day (Under 900g)",
            "key": "PACKETNEXT",
            "carrier": "EVRI",
            "conditions": [
                [
                    "Weight",
                    "<",
                    "900"
                ]
            ]
        },
        {
            "id": "ef7db004-2840-42f5-ad24-8033634c829e",
            "name": "Parcel Next Day",
            "description": "Parcel Next Day (900g and over)",
            "key": "PARCELNEXT",
            "carrier": "EVRI",
            "conditions": [
                [
                    "Weight",
                    ">=",
                    "900"
                ]
            ]
        },
        {
            "id": "72dc391b-4550-4ac5-9575-7326de7935cb,
            "name": "Two Day",
            "description": "Two Day Delivery",
            "key": "TWODAY",
            "carrier": "EVRI",
            "conditions": [
                [
                    "Weight",
                    "<=",
                    "15000"
                ]
            ]
        },
        {
            "id": "8d33af9b-bf03-474c-a4b5-c8d50ca1fe9e",
            "name": "DPD Next Day",
            "description": "DPD Next Day",
            "key": "DPDNEXT",
            "carrier": "DPD",
            "conditions": []
        }
    ]
}



Custom Fields

Custom Field Object

Custom Fields can be used across the Shipmate platform and can be used to supply custom information to carriers, invoke specific Routing Rules or display information on labels, as just a few examples.

Custom Fields may be configured inside the Shipmate web portal, or via API.

Parameters:
Parameter Description Type
name The name of the Custom Field String
key The unique key for the Custom Field, used as the key in key => value pairs String
entity The entity on Shipmate this Custom Field is for.

Can be one of SHIPMENT, PARCEL, CONTACT or SKU.
String
data_type The type of data being held in this Custom Field - see the Data Types table String
source The source of the data:

DIRECT - the data will be supplied by API or CSV file

FIXED - the data will always have the same default_value

MAPPED - the data is mapped to another attribute or custom field specified in mapped_to
String
mapped_to The key of another Custom Field, if source is MAPPED. String
default_value The value to apply to the Custom Field if data is not supplied. Acts as the fixed value if source is FIXED. String
data_validation_rules Optional validation you wish to apply to data used on this Custom Field. Validation Rules

Custom Field Data Types:

Type Key Description
Numeric NUMERIC Any numeric value can be supplied
Text TEXT Any text value can be supplied
Boolean BOOLEAN A true or false value can be supplied
List LIST The supplied value must be in a supplied list

Validation Rules Object

If additional validation is required for data entered into Custom Fields, it may be configured using the following options:

Parameters:
Parameter Description Type
is_required If data is required for this Custom Field.

Can be set for all Data Types.
Boolean
min_length States the minimum length of a string.

Can be set when data_type is TEXT
Integer
max_length States the maximum length of a string.

Can be set when data_type is TEXT
Integer
regex States a Perl-compatible Regular Expression the supplied data must match.

Can be set when data_type is TEXT
String
options Accepts comma separated, quote encapsulated (and escaped) list of options.

Can be set when data_type is LIST
String
numeric_type States the type of number to expect - INT or DECIMAL.

Can be set when data_type is NUMERIC
String
min_value States the minimum value.

Can be set when data_type is NUMERIC
Decimal
max_value States the maximum value.

Can be set when data_type is NUMERIC
Decimal

Get Custom Fields

GET /custom-fields

Retrieves an array of Custom Fields available on the account.

Example Response:

{
    "message": "Custom Fields Retrieved",
    "data": [
        {
            "id": "f013e83c-7dcf-49e6-9718-06763d4be577",
            "name": "ORDERS-TEXT-FIXED",
            "key": "ORDERS-TEXT-FIXED",
            "entity": "ORDER",
            "data_type": "TEXT",
            "default_value": "Fixed value to always use",
            "mapped_to": null
        },
        {
            "id": "6cc816ce-edad-4e08-aabf-ddcbe1d7ccc1",
            "name": "SKUS-TEXT-FIXED",
            "key": "SKUS-TEXT-FIXED",
            "entity": "SKU",
            "data_type": "TEXT",
            "default_value": "Fixed value to always use",
            "mapped_to": null
        }
    ]
}

Get Single Custom Field

GET /custom-fields/:ref

Retrieves a single Custom Field from the account where :ref is either the key or id of the individual Custom Field.

For example, both the following requests yield the same response:

GET /custom-fields/6cc816ce-edad-4e08-aabf-ddcbe1d7ccc1

GET /custom-fields/SKUS-TEXT-FIXED

Example Response:

{
    "message": "Custom Field Retrieved",
    "data": [
        {
            "id": "6cc816ce-edad-4e08-aabf-ddcbe1d7ccc1",
            "name": "SKUS-TEXT-FIXED",
            "key": "SKUS-TEXT-FIXED",
            "entity": "SKU",
            "data_type": "TEXT",
            "default_value": "Fixed value to always use",
            "mapped_to": null
        }
    ]
}

Create Custom Field

POST /custom-fields

Creates a new Custom Field on the account.

Supply JSON encoded data as per the attributes described in the Custom Field object to create your Shipment.

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.2/custom-fields

{
    "name": "SKU Text Fixed Field",
    "key": "SKU-TEXT-FIXED",
    "entity": "SKU",
    "data_type": "TEXT",
    "source": "FIXED",
    "default_value": "Fixed value to always use"
}

Example Response:

{
    "message": "Custom Field created",
    "data": {
        "id": "c9b61ad1-a5f8-4dff-88d6-076ac5745b55",
        "entity": "SKU",
        "name": "SKU Text Fixed Field",
        "key": "SKU-TEXT-FIXED",
        "data_type": "TEXT",
        "default_value": "Fixed value to always use",
        "mapped_to": null
    }
}



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

If the allow_override option is set to true, you may provide the weight and individual parcel dimensions in your POST /shipments 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 Shipment is created.

All weight values are in grammes and all dimension values are in mm.

Example Response:

{
    "message": "Packaging Options",
    "data": [
        "net_weight": true,
        "allow_override": true,
        "packaging_types": [
            {
                "name": "Small Box",
                "key": "BOX_SMALL",
                "default": false,
                "internal_width": 145,
                "internal_height": 145,
                "internal_depth": 75,
                "external_width": 150,
                "external_height": 150,
                "external_depth": 80,
                "max_weight": 2000,
                "default_weight": 1200,
                "packaging_weight": 60
            },
            {
                "name": "Medium Box",
                "key": "BOX_MEDIUM",
                "default": false,
                "internal_width": 345,
                "internal_height": 295,
                "internal_depth": 245,
                "external_width": 350,
                "external_height": 300,
                "external_depth": 250,
                "max_weight": 10000,
                "default_weight": 10000,
                "packaging_weight": 100
            },
            {
                "name": "Large Box",
                "key": "BOX_LARGE",
                "default": false,
                "internal_width": 495,
                "internal_height": 495,
                "internal_depth": 395,
                "external_width": 500,
                "external_height": 500,
                "external_depth": 400,
                "max_weight": 20000,
                "default_weight": 20000,
                "packaging_weight": 250
            },
        ]
    ]
}



SKUs

SKU Object

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

Parameters:
Parameter Description Type
id Unique system identifier String
sku SKU number used to match on your other systems String
image_url URL of Image of this SKU 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
active Whether this item is currently active in your inventory Boolean
is_stocked_item Whether this is an item kept in stock Boolean
in_stock Whether this item is currently in stock Boolean
custom_fields Array of key => value pairs JSON Key/Value
item_handling PACKABLE or NON_PACKABLE String
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
image_url URL of Image of this SKU 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 ID. 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
item_handling 1, True, Y, Yes, P or packable, in any typographical case, as PACKABLE (default)

0, False, N, No, nonpackable or non-packable, in any typographical case, as NON_PACKABLE
String
active Whether this item is currently active in your inventory

Defaults to true.
Boolean
is_stocked_item Whether this is an item kept in stock Boolean
in_stock Whether this item is currently in stock Boolean
custom_fields Array of key => value pairs JSON Key/Value

Update SKU

PUT /skus/:ref

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

Uses the same attributes as per POST /skus above. Requires all mandatory attributes in the POST method to process the update.

PATCH /skus/:ref

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

Uses the same attributes as per POST /skus above. 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": [
        {
            "id": "17db8d26-bcf0-409b-937c-9f64cf95be70",
            "sku": "TSHIRT1-XS",
            "product_name": "Shipmate Blue T-Shirt (XS)",
            ...
        },
        {
            "id": "265a0b15-9cb9-4322-9568-6587f30b7bc9",
            "sku": "TSHIRT1-S",
            "product_name": "Shipmate Blue T-Shirt (S)",
            ...
        },
        {
            "id": "19c15b14-bfac-4348-b887-03bdbe6fb081",
            "sku": "TSHIRT1-M",
            "product_name": "Shipmate Blue T-Shirt (M)",
            ...
        },
        ...
    ],
    "links": {
        "first": "https://api.shipmate.co.uk/v1.2/skus?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://api.shipmate.co.uk/v1.2/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 ID.




Tracking Events

Tracking Event Object

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

Consider using Webhooks to update tracking events. Shipmate will then update you as soon as tracking events are received, minimising load on servers.
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 Shipment 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 Shipment

GET /shipments/:ref/events

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

The returned events will be grouped by Parcel, with each Parcel response including the Shipment 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": {
            "shipment_reference": "80000234-1",
            "courier_tracking_reference": "15976602839998",
            "tracking_events": [
                {
                    "code": "SHIP01",
                    "name": "Label Created",
                    "description": "The Label has been created",
                    "date": "2024-02-22 08:48:57",
                    "type": "LABEL_CREATED"
                },
                {
                    "code": "000001022",
                    "name": "Manifested",
                    "description": "Manifested for Delivery",
                    "date": "2024-02-22 05:08:00",
                    "type": "MANIFESTED"
                },
                {
                    "code": "000001256",
                    "name": "In Transit",
                    "description": "Carrier Received",
                    "date": "2024-02-22 06:14:00",
                    "type": "IN_TRANSIT"
                },
                {
                    "code": "000001403",
                    "name": "Delivered",
                    "description": "Delivered to Outbuilding",
                    "date": "2024-02-22 13:36:00",
                    "type": "DELIVERED"
                }
            ]
        }
    }
}

Get Events by Parcel

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



Labels & Documents

Label Object

The label object represents a single Parcel in a Shipment.

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
shipment_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/:ref/label

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

Supply the Carrier's Tracking Reference as the :ref 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": [
        {
            "shipment_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": "2024-02-22 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/:ref/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 :ref identifier in your request.

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

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 Desktop Printer App or their printer for onward troubleshooting.
Arguments:
Parameter Description Type
print_to_user Optional ID of User you wish to print to String

Example Response:

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

Get Commercial Invoice

GET /shipments/:ref/commercial-invoice

Retrieves the A4 Commercial Invoice for the referenced Shipment in base_64 encoded PDF format.

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




Containers

Container Object

The Container response object contains all key details about an individual Container.

Parameters:
Parameter Description Type
id Unique system identifier String
reference Merchant supplied or system generated reference String
despatch_date In format YYYY-MM-DD e.g., 2024-12-04 String
despatch_location Location object of Despatch Address Location
delivery_service_key The Delivery Service being used to send the Container String
carrier The Carrier name, e.g., FedEx String
carrier_account The Carrier Account name, e.g., FedEx - Primary Account String
service_name The Delivery Service name, e.g., IPD - International Distribution Freight String
full_service_name The Carrier and Service name, e.g., FedEx - IPD - International Distribution Freight String
tracking_reference Tracking reference from Carrier String
consolidation_reference Consolidation reference from Carrier (could be same as the Tracking reference) String
clearance_country Country object containing two character ISO 3166-1 clearance country code, e.g., NL, FR, DE, ES and full name Country
clearance_location The Carrier's clearance location code String
clearance_location_name The full name of the clearance location String
max_parcels Maximum number of Parcels allowed in Container. null if unlimited. Integer
max_items Maximum number of Items allowed in Container across all Parcels. null if unlimited. Integer
max_weight Maximum weight allowed of Parcels in Container in grammes. null if unlimited. Integer
max_value Maximum value of contents allowed in Container in pence / cents. null if unlimited. Integer
value_currency ISO 4217 3-character currency code e.g., GBP, EUR, USD. String
parcels Current number of Parcels in Container. Integer
items Current number of Items in Container across all Parcels. Integer
weight Current weight of Parcels in Container in grammes. Integer
value Current value of contents in Container in pence / cents. Integer
status Current status of Container: Open or Closed. String

Example Response:

{
    "message": "Container created",
    "data": {
        "id": "396b0397-03e2-4dcc-b20a-c957462dbfd6",
        "reference": "C24242001",
        "despatch_date": "2024-08-30",
        "despatch_location": {
            "id": "bae33e4a-5996-423d-acb3-e663e42e6e34",
            "code": "DC1",
            "name": "Derby Office",
            "type": "STORE",
            "telephone": "01332 460888",
            "email": "info@shipmate.co.uk",
            "address_name": "Derby Office",
            "address_line_1": "Friar Gate Studios",
            "address_line_2": "Ford Street",
            "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-11-23 10:19:47"
        },
        "delivery_service_key": "IPD_INTERNATIONAL_DISTRIBUTION_PRIORITY_CONSOLIDATION",
        "carrier": "FedEx",
        "carrier_account": "FedEx",
        "service_name": "IPD - International Distribution Priority",
        "full_service_name": "FedEx - IPD - International Distribution Priority",
        "tracking_reference": "794657211571",
        "consolidation_reference": "794657211571",
        "clearance_country": {
            "code": "FR",
            "name": "France"
        },
        "clearance_location": "IDSI",
        "clearance_location_name": "Paris",
        "max_parcels": 999,
        "max_items": 9999,
        "max_weight": null,
        "max_value": null,
        "value_currency": "GBP",
        "parcels": 2,
        "items": 3,
        "weight": 700,
        "value": 1833,
        "status": "Open"
    }
}

Create Container

POST /containers

Creates a new Container you can then add Shipments to.

Supply the following data to this method to create your new Container. On success, the Shipmate API will respond with a Container object.

Arguments:
Parameter Description Type
reference Optional, generates reference if omitted in format: CYYDDDSSS e.g., C24099001 String
despatch_date Optional, uses today’s date if omitted. Supply in format YYYY-MM-DD e.g., 2024-12-04 String
despatch_location Location Code or ID. Optional, uses Default Location if omitted String
delivery_service_key The Delivery Service being used to send the Container (must be a Consolidation Service) String
clearance_country The two character ISO 3166-1 clearance country code, e.g., NL, FR, DE, ES String
clearance_location The Carrier's clearance location code String
value_currency ISO 4217 3-character currency code e.g., GBP, EUR, USD. Optional, defaults to account currency. 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.2/containers

{
    "reference": "C24242001",
    "despatch_date": "2024-08-30",
    "despatch_location": "DC1",
    "delivery_service_key": "IPD_INTERNATIONAL_DISTRIBUTION_PRIORITY_CONSOLIDATION",
    "clearance_country": "FR",
    "clearance_location": "IDSI",
    "value_currency: "GBP"
}

Add Shipment to Container

Once the Container is created, you simply create Shipments as normal however can now supply an additional container_reference attribute to apply the Shipment to the Container.

Additional validation will take place to make sure the Shipment can be sent using the requested Container, and the response object will also contain the container_reference attribute.

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.2/shipments

{
    "shipment_reference": "80000002",
    "delivery_service_key": "FEDEX_IPD_PARCEL_EU",
    "container_reference": "C24242001",
    "to_address": {
        "name": "Herr Shipmate Test",
        "line_1": "Hauptstraße 35",
        "city": "Berlin",
        "postcode": "010119",
        "country": "DE"
    },
    "parcels": [
        {
            "reference": "80000002-1",
            "weight": 3000,
            "width": 20,
            "length": 10,
            "depth": 15,
            "items" : {
                ...
            }
            "custom_fields":  {
                "category": "Books",
            }
        },
        ...
    ]
}

Get Container

GET /containers/:ref

Retrieves a Container.

Supply the Container's ID or Reference as the :ref identifier in your request.

Get Container Label(s)

GET /containers/:ref/label

Retrieves the Container's shipping label(s). will return a label in either base_64 encoded PDF or ZPL format as requested.

Supply the Container's ID or Reference as the :ref identifier in your request.

Arguments:
Parameter Description Type
format The format that the label should be returned in: ZPL or PDF. Defaults to ZPL. String

Get Container Documents

GET /containers/:ref/documents

Retrieves Carrier Documents for the Container in base_64 encoded PDF format.

Depending on the carrier being used, this method may only be accessed once the Container is Closed.

Supply the Container's ID or Reference as the :ref identifier in your request.

Get Commercial Invoice

GET /containers/:ref/commercial-invoice

Retrieves an A4 Commercial Invoice for the Container in base_64 encoded PDF format.

Depending on the carrier being used, this method may only be accessed once the Container is Closed.

Supply the Container's ID or Reference as the :ref identifier in your request.

Get Container Shipments

GET /containers/:ref/shipments

Retrieves a meta-data list of Shipments within the Container.

Supply the Container's ID or Reference as the :ref identifier in your request.

Example Response:

{
    "message": "Container shipments retrieved",
    "data": {
        "shipments": [
            {
                "id": "719c1b15-b5f2-4875-9751-37dd44999a44",
                "reference": "S-1725027352",
                "tracking_reference": "794657221951",
                "parcels": 1,
                "items": 1,
                "weight": 300,
                "value": 833
            },
            {
                "id": "1920aab8-d885-40e4-9a20-aaeba26e9cc3",
                "reference": "S-1725027508",
                "tracking_reference": "794657222237",
                "parcels": 1,
                "items": 2,
                "weight": 400,
                "value": 1000
            }
        ]
    }
}

Close Container

PATCH /containers/:ref/close

Closes the container and runs the Carrier's Container close routine that will generate documents such as the Certificate of Origin, Commercial Invoice and Labels.

It will no longer be possible to add further Shipments to this Container once it is Closed.

Supply the Container's ID or Reference as the :ref identifier in your request.

Delete Container

DELETE /containers/:ref

Deletes the Container. Can only be used on empty Containers, or whereby all constituent Shipments have been cancelled.

Supply the Container's ID or Reference as the :ref identifier in your request.




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
Hover
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
custom_fields Array of key-value pair objects of Custom Field values, e.g., {"key": "MY_FIELD", "value": "Some Value"} Array

Payload Structure (ZPL and PDF Labels)

This has the same structure as the Creation and Cancellation events together with an additional labels attribute containing a string of the labels in the requested format.

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
labels ZPL code or Base64-encoded PDF string String
custom_fields Array of key-value pair objects of Custom Field values, e.g., {"key": "MY_FIELD", "value": "Some Value"} Array

Payload Structure (PNG Labels)

This has the same structure as the Creation and Cancellation events together with an additional labels attribute containing an array of Base64-encoded PNG labels.

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
labels Array of Base64-encoded PNG strings, one for each label Array
custom_fields Array of key-value pair objects of Custom Field values, e.g., {"key": "MY_FIELD", "value": "Some Value"} Array

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.2.3 - October 2024

Updates include:

Version 1.2.2 - August 2024

Updates include:

  • NEW FEATURE – Containerised Shipments feature supports shipment consolidation services
  • Improved – Webhooks now include a new custom_fields attribute in the payload

Version 1.2.1 - April 2024

Updates include:

  • SKUs now accept an image_url attribute. This downloads a copy of the image and stores it on Shipmate servers to provide consistent functionality with the web portal
  • SKUs now accept an active attribute that defaults to true to provide consistent functionality with the web portal
  • SKUs now have both PUT and PATCH endpoints to conform with RESTful principles

Version 1.2.0 - March 2024

Updates include:

  • New API endpoint URL
  • Consignments endpoints now known as Shipments.
  • Shipment Object now accepts a customs_declaration attribute
  • Shipment Object now accepts recipient_vat_number and recipient_eori_number attributes to supply VAT / EORI numbers for international destinations.
  • Shipment Object now accepts print_labels and print_to_user attributes to send retrieved labels directly to a connected printer using the Shipmate Desktop App.
  • POST /shipments now returns the estimated delivery date
  • Customs Declaration Object now accepts 11 additional attributes to assist with creation of Commercial Invoices
  • New POST /shipments/get-services endpoint to retrieve Delivery Services, costs and estimated delivery date for Shipments
  • Items Object now accepts item_weight and item_line_id
  • New Custom Fields functionality for Shipments, Parcels, Contacts and SKUs, replacing Parcel Attributes
  • Shipment, Parcel and SKU Objects now accept a custom_fields key => value pair array
  • New Webhooks containing ZPL, PDF or PNG labels

Breaking changes include:

  • All instances of sender_id replaced with merchant_id for consistency
  • Authentication response now contains a UUID string for the user.id and user.merchant_id values instead of numeric
  • GET /services response now contains a UUID string for the id value instead of numeric
  • GET /locations response attribute uuid has been renamed id for consistency
  • GET /skus response attribute uuid has been renamed id for consistency
  • GET /users response attribute uuid has been renamed id for consistency
  • GET /packaging-options response, Packaging Type dimensions changed from cm to mm for consistency with SKU dimensions
  • attributes removed from Parcel object, replaced with custom_fields
  • GET /shipments/:ref/events response attribute sender_reference renamed shipment_reference for consistency

Deprecations include:

  • Consignments noun may continue to be used for this version but will be phased out in future versions.
  • Shipment Object attribute service_key has been aliased to delivery_service_key. service_key will be phased out in future versions.

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