Track & trace page

JavaScript to integrate a shop frontend (or any webpage) with parcelLab. This plugin can be used to retrieve and display the checkpoints of a tracking (Track & trace page).

Quick install

First, create an empty landing page in your shop e.g. at /track-and-trace

Now copy-paste the following snippet somewhere in the <body /> (not the <head />) of your page where you want the track & trace to be displayed. This will automatically load our JS snippet and default CSS then render the plugin into the defined DOM node:

parcellab-track-and-trace-snippet.html
<div id="parcellab-track-and-trace"></div>
<script>
(function (prcl) {/* Load parcelLab assets ... */
if (window.ParcelLab) {return prcl();}function a() {var styles = document.createElement('link'); styles.rel = 'stylesheet'; styles.href = 'https://cdn.parcellab.com/css/v3/parcelLab.min.css'; document.getElementsByTagName('head')[0].appendChild(styles); }function b(cb) { var script = document.createElement('script'); script.async = true; script.src = 'https://cdn.parcellab.com/js/v3/parcelLab.min.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(script); script.onload = cb; } a(); b(prcl);
})(function () {/* ... plugin is ready to use: */
var options = {};
var pl = new ParcelLab('#parcellab-track-and-trace', options);
pl.initialize();
window._prcl = pl;
});
</script>

Alternative: Hosted version

The tracking website can be reached at either versand-status.de, paket-fuer-mich.de or delivery-status.com. The URL scheme is identical to the API endpoint, i.e.:

How to use

After the page has been prepared as above, it is ready for use. The plugin supports track and trace for single parcels, but also a consolidated one for whole orders.

Usage with parcels

The plugin expects two parameters to be set in the URL: the courier and trackingNo. If these are set and valid, it will render an action box on the left side displaying the currently most relevant information and a complete history on the right side.

https://myshop.com/tracking-and-trace?courier=dhl-germany&trackingNo=00PL16120004

A list of all possible courier codes can be found in these docs as well, though is not required as the URL to this page will automatically be generated by parcelLab.

Usage with orders

The more advanced usage is for orders. This will render all parcels of an order, generate an overview and list all individual parcels.

https://myshop.com/tracking-and-trace?u=1612197&orderNo=00PL004

We recommend setting the userId (in the example above 1612197, but will be your individual one) directly in the options rather than through the URL (see below on how to do that). If, and only if, you're running several shops with overlapping ranges of order numbers in your account, you can also set the client to limit trackings to a specific shop in the parcelLab system.

Option

Description

Sample

userId

Your user id in the parcelLab System

1612197

client

The parcelLab-internal shop id associated to a specific shop

parcelfashion-US

Testing

You can test the implementation and display of the track and trace by using our sample parcels. Append the following queries to the URL of the page where you installed our plugin:

Display

Query

Sample

Calendar sheet

?courier=dhl-germany&trackingNo=00PL16120004

Link

Pickup map

?courier=dhl-germany&trackingNo=00PL16120006

Link

Icon

?courier=dhl-germany&trackingNo=00PL16120008

Link

Consolidated order

?u=1612197&orderNo=00PL004

Link

Typical use cases

You can define options by passing an Object as the second argument when creating a new ParcelLab Object. The use cases below list all possible options.

<script type="text/javascript">
...
var options = { rerouteButton: 'left' };
var parcelLab = new ParcelLab('#pl-trace', options);
parcelLab.initialize(); // <~ delivery status will be display to dom-elem. with id="pl-trace"
...
</script>

All options below can also set through the URL:

.../track-and-trace?...&rerouteButton=left

Delivery options

Option

Description

Sample

rerouteButton

Where to show delivery options button, can be left or right

left

Also known as rerouting or "Empfängerservices" in German, delivery options give the recipient the possibility to change how, when and where he wants to receive their parcel. This is done by linking to the carrier's page whenever delivery options are available. This can be activated by setting this option:

Sample for reroute options (German)

Order search form

The plugin can also be used to show a search form for the case if either the page has been accessed by the customer manually or if tracking/ order cannot be found.

Option

Description

Sample

show_searchForm

Activates a search form that will be rendered if either tracking was not found or no trackingNo/orderNo was given, requires userId

true

show_zipCodeInput

Activates the zip code field for the search form, needs to be activated on the system side by the parcelLab team as well

true

These two options can be set directly in the options when initialising the plugin to keep the URL clean:

search-form-options.html
<script type="text/javascript">
...
var options = { userId: 1612197, show_searchForm: true, show_zipCodeInput: true };
var parcelLab = new ParcelLab('#pl-trace', options);
parcelLab.initialize(); // <~ delivery status will be display to dom-elem. with id="pl-trace"
...
</script>
Sample for the search form with zip input (German, mobile)

If you want to the search form to require a zip code, you need to reach out to our team so we activate this option in the backend.

The script can render an image banner with a link if both of the following two optional parameters are given:

Option

Description

Sample

banner_image

Complete URL of image

https://parcelfashion.co/img/banner.png

banner_link

Traget URL of banner

https://parcelfashion.co/sale

Sample of a banner ad on the track & trace page

For the banner_image we recommend PNG or JPG with a ratio of 0.7 : 1, but any other format can be chosen as well. A recommended solution is 700 x 1000 px for optimal rendering on retina screens, with texts being at least 16px high.

Custom Translations

You can change the static plugin text parts with your own translations. For that just add the attribute customTranslations to your options and insert your custom texts. You can find the full list of texts, used by the plugin here. If you don't define a language in your customTranslations, the plugin will fallback to the original text, when rendering in this language.

Example: Lets change the texts for the search form.

custom-translations.js
...
options.customTranslations = {
de: {
searchOrder: 'Bestellnummer eingeben', // translation for search input placeholder
zip: 'PLZ eingeben', // translation for zip input placeholder
search: 'Suche starten', // translation for search button text
},
en: {
searchOrder: 'Type order number',
zip: 'Type zip code',
search: 'Start search',
},
}
var parcelLab = new ParcelLab('#pl-trace', options);
parcelLab.initialize();

Styling

Option

Description

Sample / default

borderColor

border color for the boxes

#eee

borderRadius

border radius for the boxes and buttons

4px

buttonColor

text color for buttons

#333

buttonBackground

background color for buttons

#e6e6e6

iconColor

color for the status icons

#000

margin

margin for outer container

0px

In this example, we will set the box and button border-radius to 0px and make the buttons black by setting the options object:

The plugin can be styled by setting customStyles. Possible values are:

custom-style.js
<script>
(function (prcl) {/* Load parcelLab assets ... */
if (window.ParcelLab) {return prcl();}function a() {var styles = document.createElement('link'); styles.rel = 'stylesheet'; styles.href = 'https://cdn.parcellab.com/css/v3/parcelLab.min.css'; document.getElementsByTagName('head')[0].appendChild(styles); }function b(cb) { var script = document.createElement('script'); script.async = true; script.src = 'https://cdn.parcellab.com/js/v3/parcelLab.min.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(script); script.onload = cb; } a(); b(prcl);
})(function () {/* ... plugin is ready to use: */
var options = {
styles: true,
customStyles: {
borderRadius: '0px',
buttonBackground: '#000000',
buttonColor: '#fff',
}
};
var pl = new ParcelLab('#parcellab-track-and-trace', options);
pl.initialize();
window._prcl = pl;
});
</script>
<div id="parcellab-track-and-trace"></div>

When setting customStyles via the URL query, the customStyles can be dropped, any # has to be removed from hex color codes and all content must be URI encoded, e.g.: www.versand-status.de/?trackingNo=...&borderRadius=2px&buttonColor=e6e6e6

As a last resort, you can also overwrite the CSS:

If you want to use the plugin in a non-customer facing website (e.g. an internal page for customer support), it is recommended to hide the action box like so:

<style> div#pl-action-box-container { display: none; } </style>

onRendered Hook

There is another option called onRendered which expects a function (state) with state being an object describing the pulled information:

var plRenderedHook = function (state) {
// Do something with the DOM or the information
};
var parcelLab = new ParcelLab('#parcellab-track-and-trace', { onRendered: plRenderedHook });
parcelLab.initialize();

This can be used to alter the DOM programmatically after our plugin has rendered its content.

Programmatic access

The selection of the tracking(s) to be displayed is typically performed through the URL (see above), but can also be done in-code if required for the shop. Then, the following options can be used:

Option

Description

Sample

courier

The parcelLab courier code

dhl-germany

trackingNo

The tracking number

0034000000001

userId

Your parcelLab user ID

1612197

orderNo

The associated orderNo of trackings

ORD-123

selectedTrackingNo

When opening the page with userId / orderNo, select a specific tracking to be highlighted

0034000000001

Still not enough?

Alternatively, the CSS and JS can be included manually:

manual-parcellab-track-and-trace-snippet.html
<link href="https://cdn.parcellab.com/css/v3/parcelLab.min.css" rel="stylesheet">
<script src="https://cdn.parcellab.com/js/v3/parcelLab.min.js" charset="utf-8"></script>

Or view our guides for installing with shop systems:

The code is also available as Open Source on Github. Feel free to fork or clone, change and host, or create pull requests: