Learn how to add new shipping carriers to Shopp for use when sending shipment notices from the order management screen.

Adding Shipping Carriers to Shopp

mailrail

Adding Shipping Carriers to Shopp

In the Shopp shipping settings, a selection of Shipping Carriers are provided by default. At the time of writing, the available carriers are UPS, FedEx, Aramex, DHL and TNT (Shown in Fig.1 below).

default-list

Fig.1 Shipping Carriers shown as checkboxes

shipping-notice-1

Fig.2 The Carrier is selectable when sending the Shipping Notice

These Carriers are used when sending Shipping Notices from within the Order Management Screen (Shown in Fig.2 Above). The Store Manager can enter a Tracking Number which gets forwarded to the Customer as a link, enabling them to visit the Carrier’s tracking website directly.

Adding a new Shipping Carrier

Adding a new Shipping Carrier to the list is straightforward when we make use of the shopp_shipping_carriers Filter which is part of the Shopp API. For simplicity we’ll be adding some code to the WordPress Theme’s functions.php file, but there’s no reason that this code couldn’t be added via your own custom plugin.

To avoid interference with any existing Theme modifications, this code should be added to the bottom of the currently active Theme’s functions.php file

For the purpose of this tutorial, we’re going to use the real-world example of adding UK-based carriers Royal Mail and Parcelforce.

add_filter('shopp_shipping_carriers', 'add_shipping_carriers');

function add_shipping_carriers( $carriers ) {

    //Adding the Royal Mail carrier first, it's the way the Queen would want it!
    $carriers['royal'] = new ShippingCarrier( // Maximum of 5 chars for short name i.e. 'royal'
        'Royal Mail', // This is the name of the Carrier
        'http://www.royalmail.com', // The Carrier's site URL
        '*', // The 2-Digit ISO country code, or * for all
        'http://www.royalmail.com/portal/rm/track?trackNumber=%s', // The Carrier's tracking URL
        '/^[a-zA-Z]{2}[0-9]{9}[a-zA-Z]{2}$/' // The Regular Expression to match the tracking code
    );

    //Adding Parcelforce second
    $carriers['pfce'] = new ShippingCarrier(
        'Parcel Force',
        'http://www.parcelforce.com/',
        '*',
        'http://www.parcelforce.com/portal/pw/track?trackNumber=%s',
        '/^[a-zA-Z]{2}[0-9]{9}[a-zA-Z]{2}$/'
    );

    //Returning the new array with the added carriers
    return $carriers;
}

Hopefully the code comments included above explain what’t happening quite well, but we’ll go into some more detail here:

The Carrier’s Tracking URL

The carrier likely has a tracking website which can be visited for updated tracking details. For the first example used here, the Royal Mail tracking URL (Source info) is:
http://www.royalmail.com/portal/rm/track?trackNumber=[TRACKING NUMBER]

So in our code, we set this as the tracking URL, swapping [TRACKING NUMBER] with %s ready for the string replace function, like so:
'http://www.royalmail.com/portal/rm/track?trackNumber=%s'

The Regular Expression (RegEx) pattern

Tracking numbers or codes used by Shipping Carriers invariably adhere to a format. In the case of Royal Mail and Parcelforce the format is 2 letters, 9 numbers, 2 letters. e.g. GB123456789YZ. Shopp uses a RegEx pattern to check that the Tracking code entered follows the correct format. If you’re not familiar with Regular Expressions there are plenty of resources for that, but as a very brief introduction and explanation:

We want to match 2 letters followed by 9 numbers followed by 2 letters. For ease of use we should make it case-insensitive. [a-zA-Z] matches any letter from “a” to “z” in upper or lower case. {2} matches 2 occurrences of the previous item. [0-9] will match any number and {9} looks for 9 occurrences of it. We can use those small patterns to build this one:
[a-zA-Z]{2}[0-9]{9}[a-zA-Z]{2}.

Finally we want to make sure that the code is only 13 chracters long, so we make use if ^ which matches the start of a string, and $ which matches the end. The final pattern will match these codes “DP127495724mw” and “qL926041752PB” but not “swq953631953f” or “GB0482635qY” for example.

The Result

Once the code provided above has been added to the functions.php file and saved, the result should look like this:

both-all

Fig.3 Both lists showing the newly added Carriers

Displaying a shorter Shipping Carriers list

If you’re adding Shipping Carriers for a country other than the USA you might want to remove the existing default carriers from the list. There are two ways to do this:

Removing unwanted Shipping Carriers in Admin

The easiest way to do this is via the WordPress Admin area. Navigate to Shopp → Setup → Shipping. On that page under ‘Shipping Carriers’ (See in Fig.1 earlier in this article) you can select which Carriers will be displayed in the Order Manager screen. For more information please see the Shipping Settings docs

Removing Shipping Carriers programatically

For a more permanent solution, one that might stop a client or employee interfering with the Carriers list, we can make a change to the add_shipping_carriers() function we’ve just written. When the function is called by the filter, the current Shipping Carriers array is passed to it, and we could empty it before adding our new Carriers. For example:

add_filter('shopp_shipping_carriers', 'add_shipping_carriers');

function add_shipping_carriers( $carriers ) {
    // Empty the array of carriers passed to this function.
    $carriers = array();

    //Adding the Royal Mail carrier first, it's the way the Queen would want it!
    $carriers['royal'] = new ShippingCarrier( // Maximum of 5 chars for short name i.e. 'royal'
    // etc etc... the rest of the function
}

The result should look something like this:

both-short

Fig.4 Both lists showing only the two newly added Carriers

Conclusion

Hopefully that explains how the shopp_shipping_carriers Filter works. If you need some more info, please follow the suggestions in the ‘Heed Help?’ box below

Avatar of Ben Hutchings

By

Ben Hutchings is a Freelance Web Developer from the South West of England, specialising in WordPress and its associated technologies.

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.

Skip to toolbar